Living Standard — Last Updated 23 January 2025
innerText and outerText propertiesbody elementarticle elementsection elementnav elementaside elementh1, h2, h3, h4, h5, and h6
elementshgroup elementheader elementfooter elementaddress elementp elementhr elementpre elementblockquote elementol elementul elementmenu elementli elementdl elementdt elementdd elementfigure elementfigcaption elementmain elementsearch elementdiv elementa elementem elementstrong elementsmall elements elementcite elementq elementdfn elementabbr elementruby elementrt elementrp elementdata elementtime elementcode elementvar elementsamp elementkbd elementsub and sup elementsi elementb elementu elementmark elementbdi elementbdo elementspan elementbr elementwbr elementa and area elementsa and area elementsalternate"author"bookmark"canonical"dns-prefetch"expect"external"help"icon"license"manifest"modulepreload"nofollow"noopener"noreferrer"opener"pingback"preconnect"prefetch"preload"privacy-policy"search"stylesheet"tag"terms-of-service"picture elementsource elementimg elementsource,
img, and link elementsiframe elementembed elementobject elementvideo elementaudio elementtrack elementTrackEvent interfacemap elementarea elementtable elementcaption elementcolgroup elementcol elementtbody elementthead elementtfoot elementtr elementtd elementth elementtd and th elementsform elementlabel elementinput elementtype attributetype=hidden)type=text) state and Search state (type=search)type=tel)type=url)type=email)type=password)type=date)type=month)type=week)type=time)type=datetime-local)type=number)type=range)type=color)type=checkbox)type=radio)type=file)type=submit)type=image)type=reset)type=button)input element attributesmaxlength and minlength attributessize attributereadonly attributerequired attributemultiple attributepattern attributemin and max attributesstep attributelist attributeplaceholder attributeinput element APIsbutton elementselect elementdatalist elementoptgroup elementoption elementtextarea elementoutput elementprogress elementmeter elementfieldset elementlegend elementname attributedirname attributemaxlength attributeminlength attributedisabled attributeSubmitEvent interfaceFormDataEvent interfacedetails elementsummary elementa element to define a commandbutton element to define a commandinput element to define a commandoption element to define a commandaccesskey attribute
on a legend element to define a commandaccesskey
attribute to define a command on other elementsdialog elementscript elementnoscript elementtemplate elementslot elementcanvas elementPath2D objectsImageBitmap rendering contextOffscreenCanvas interfacecanvas elementsCustomElementRegistry interfacehidden attributecontenteditable content attributedesignMode getter and setterinputmode attributeenterkeyhint
attributepopover attributeWindow,
WindowProxy, and Location objectsWindow objectWindowProxy exotic objectLocation interfaceHistory interfaceNavigation interfaceNavigationHistoryEntry interfaceNavigationActivation interfacenavigate eventNotRestoredReasons interfacemultipart/x-mixed-replace
documentsX-Frame-Options` headerRefresh` headerWindowOrWorkerGlobalScope mixinbutton elementdetails and summary elementsinput element as a text entry widgetinput element as domain-specific widgetsinput element as a range controlinput element as a color
wellinput element as a checkbox and radio button widgetsinput element as a file upload controlinput element as a buttonmarquee elementmeter elementprogress elementselect elementtextarea elementThis specification depends on Infra. [INFRA]
This specification refers to both HTML and XML attributes and IDL attributes, often in the same context. When it is not clear which is being referred to, they are referred to as content attributes for HTML and XML attributes, and IDL attributes for those defined on IDL interfaces. Similarly, the term "properties" is used for both JavaScript object properties and CSS properties. When these are ambiguous they are qualified as object properties and CSS properties respectively.
Generally, when the specification states that a feature applies to the HTML syntax or the XML syntax, it also includes the other. When a feature specifically only applies to one of the two languages, it is called out by explicitly stating that it does not apply to the other format, as in "for HTML, ... (this does not apply to XML)".
In the context of the DOM structures, the terms HTML
document and XML document are used as defined in
DOM, and refer specifically to two different modes that Document objects
can find themselves in. [DOM] (Such uses are always hyperlinked to their
definition.)
In the context of byte streams, the term HTML document refers to resources labeled as
text/html, and the term XML document refers to resources labeled with an XML
MIME type.
For simplicity, terms such as shown, displayed, and visible might sometimes be used when referring to the way a document is rendered to the user. These terms are not meant to imply a visual medium; they must be considered to apply to other media in equivalent ways.
To run steps in parallel means those steps are to be run, one after another, at the same time as other logic in the standard (e.g., at the same time as the event loop). This standard does not define the precise mechanism by which this is achieved, be it time-sharing cooperative multitasking, fibers, threads, processes, using different hyperthreads, cores, CPUs, machines, etc. By contrast, an operation that is to run immediately must interrupt the currently running task, run itself, and then resume the previously running task.
To avoid race conditions between different in parallel algorithms that operate on the same data, a parallel queue can be used.
For CSS style sheets, we tentatively define here that
their critical subresources are other style sheets imported via @import
rules, including those indirectly imported by other imported style sheets.
Except where otherwise stated, all elements defined or mentioned in this specification are in
the HTML namespace ("http://www.w3.org/1999/xhtml"), and all
attributes defined or mentioned in this specification have no namespace.
Attribute names are said to be XML-compatible if they match the Name production defined in XML and they contain no U+003A COLON
characters (:). [XML]
The insertion steps for the HTML Standard, given insertedNode, are defined as the following:
If insertedNode is an element whose namespace is the HTML namespace, and this standard defines HTML element insertion steps for insertedNode's local name, then run the corresponding HTML element insertion steps given insertedNode.
If insertedNode is a form-associated element or the ancestor of a form-associated element, then:
If the form-associated element's parser inserted flag is set, then return.
If insertedNode is an Element that is not on the
stack of open elements of an HTML parser, then
process internal resource links given insertedNode's
node document.
The post-connection steps for the HTML Standard, given insertedNode, are defined as the following:
If insertedNode is an element whose namespace is the HTML namespace, and this standard defines HTML element post-connection steps for insertedNode's local name, then run the corresponding HTML element post-connection steps given insertedNode.
The removing steps for the HTML Standard, given removedNode and oldParent, are defined as the following:
Let document be removedNode's node document.
If document's focused area is removedNode, then set document's focused area to document's viewport, and set document's relevant global object's navigation API's focus changed during ongoing navigation to false.
If removedNode is an element whose namespace is the HTML namespace, and this standard defines HTML element removing steps for removedNode's local name, then run the corresponding HTML element removing steps given removedNode and oldParent.
If removedNode is a form-associated element or the ancestor of a form-associated element, then:
If the form-associated element has a form owner and the form-associated element and its form owner are no longer in the same tree, then reset the form owner of the form-associated element.
If removedNode's popover attribute is not in
the no popover state, then run the hide
popover algorithm given removedNode, false, false, and false.
A node is inserted into a document when the insertion steps are invoked with it as the argument and it is now in a document tree. Analogously, a node is removed from a document when the removing steps are invoked with it as the argument and it is now no longer in a document tree.
A node becomes connected when the insertion steps are invoked with it as the argument and it is now connected. Analogously, a node becomes disconnected when the removing steps are invoked with it as the argument and it is now no longer connected.
A node is browsing-context connected when it is connected and its shadow-including root's browsing context is non-null. A node becomes browsing-context connected when the insertion steps are invoked with it as the argument and it is now browsing-context connected. A node becomes browsing-context disconnected either when the removing steps are invoked with it as the argument and it is now no longer browsing-context connected, or when its shadow-including root's browsing context becomes null.
The construction "a Foo object", where Foo is
actually an interface, is sometimes used instead of the more accurate "an object implementing the
interface Foo".
An IDL attribute is said to be getting when its value is being retrieved (e.g. by author script), and is said to be setting when a new value is assigned to it.
If a DOM object is said to be live, then the attributes and methods on that object must operate on the actual underlying data, not a snapshot of the data.
Typically such content handlers are provided by third parties, though a user agent can also designate built-in content handlers as plugins.
A user agent must not consider the types text/plain and
application/octet-stream as having a registered plugin.
Since different users having different sets of plugins provides a
tracking vector that increases the chances of users being uniquely identified, user agents are
encouraged to support the exact same set of plugins for each
user.
A character encoding, or just encoding where that is not ambiguous, is a defined way to convert between byte streams and Unicode strings, as defined in Encoding. An encoding has an encoding name and one or more encoding labels, referred to as the encoding's name and labels in the Encoding standard. [ENCODING]
This specification describes the conformance criteria for user agents (relevant to implementers) and documents (relevant to authors and authoring tool implementers).
User agents fall into several (overlapping) categories with different conformance requirements.
Web browsers that support the XML syntax must process elements and attributes from the HTML namespace found in XML documents as described in this specification, so that users can interact with them, unless the semantics of those elements have been overridden by other specifications.
Web browsers that support the HTML syntax must process documents labeled with an HTML MIME type as described in this specification, so that users can interact with them.
User agents that support scripting must also be conforming implementations of the IDL fragments in this specification, as described in Web IDL. [WEBIDL]
User agents that process HTML and XML documents purely to render non-interactive versions of them must comply to the same conformance criteria as web browsers, except that they are exempt from requirements regarding user interaction.
User agents, whether interactive or not, may be designated (possibly as a user option) as supporting the suggested default rendering defined by this specification.
This is not required. In particular, even user agents that do implement the suggested default rendering are encouraged to offer settings that override this default to improve the experience for the user, e.g. changing the color contrast, using different focus styles, or otherwise making the experience more accessible and usable to the user.
User agents that are designated as supporting the suggested default rendering must, while so designated, implement the rules the Rendering section defines as the behavior that user agents are expected to implement.
Implementations that do not support scripting (or which have their scripting features disabled entirely) are exempt from supporting the events and DOM interfaces mentioned in this specification. For the parts of this specification that are defined in terms of an events model or in terms of the DOM, such user agents must still act as if events and the DOM were supported.
Conformance checkers must verify that a document conforms to the applicable conformance
criteria described in this specification. Automated conformance checkers are exempt from
detecting errors that require interpretation of the author's intent (for example, while a
document is non-conforming if the content of a blockquote element is not a quote,
conformance checkers running without the input of human judgement do not have to check that
blockquote elements only contain quoted material).
Conformance checkers must check that the input document conforms when parsed without a browsing context (meaning that no scripts are run, and that the parser's scripting flag is disabled), and should also check that the input document conforms when parsed with a browsing context in which scripts execute, and that the scripts never cause non-conforming states to occur other than transiently during script execution itself. (This is only a "SHOULD" and not a "MUST" requirement because it has been proven to be impossible. [COMPUTABLE])
The term "HTML validator" can be used to refer to a conformance checker that itself conforms to the applicable requirements of this specification.
Applications and tools that process HTML and XML documents for reasons other than to either render the documents or check them for conformance should act in accordance with the semantics of the documents that they process.
Authoring tools and markup generators must generate conforming documents. Conformance criteria that apply to authors also apply to authoring tools, where appropriate.
Authoring tools are exempt from the strict requirements of using elements only for their specified purpose, but only to the extent that authoring tools are not yet able to determine author intent. However, authoring tools must not automatically misuse elements or encourage their users to do so.
When an authoring tool is used to edit a non-conforming document, it may preserve the conformance errors in sections of the document that were not edited during the editing session (i.e. an editing tool is allowed to round-trip erroneous content). However, an authoring tool must not claim that the output is conformant if errors have been so preserved.
Authoring tools are expected to come in two broad varieties: tools that work from structure or semantic data, and tools that work on a What-You-See-Is-What-You-Get media-specific editing basis (WYSIWYG).
The former is the preferred mechanism for tools that author HTML, since the structure in the source information can be used to make informed choices regarding which HTML elements and attributes are most appropriate.
However, WYSIWYG tools are legitimate. WYSIWYG tools should use elements they know are
appropriate, and should not use elements that they do not know to be appropriate. This might in
certain extreme cases mean limiting the use of flow elements to just a few elements, like
div, b, i, and span and making liberal use
of the style attribute.
All authoring tools, whether WYSIWYG or not, should make a best effort attempt at enabling users to create well-structured, semantically rich, media-independent content.
For compatibility with existing content and prior specifications, this specification describes two authoring formats: one based on XML, and one using a custom format inspired by SGML (referred to as the HTML syntax). Implementations must support at least one of these two formats, although supporting both is encouraged.
Some conformance requirements are phrased as requirements on elements, attributes, methods or objects. Such requirements fall into two categories: those describing content model restrictions, and those describing implementation behavior. Those in the former category are requirements on documents and authoring tools. Those in the second category are requirements on user agents. Similarly, some conformance requirements are phrased as requirements on authors; such requirements are to be interpreted as conformance requirements on the documents that authors produce. (In other words, this specification does not distinguish between conformance criteria on authors and conformance criteria on documents.)
This specification relies on several other underlying specifications.
The following terms are defined in Infra: [INFRA]
The Unicode character set is used to represent textual data, and Encoding defines requirements around character encodings. [UNICODE]
The following terms are used as defined in Encoding: [ENCODING]
Implementations that support the XML syntax for HTML must support some version of XML, as well as its corresponding namespaces specification, because that syntax uses an XML serialization with namespaces. [XML] [XMLNS]
Data mining tools and other user agents that perform operations on content without running scripts, evaluating CSS or XPath expressions, or otherwise exposing the resulting DOM to arbitrary content, may "support namespaces" by just asserting that their DOM node analogues are in certain namespaces, without actually exposing the namespace strings.
This specification also non-normatively mentions the XSLTProcessor
interface and its transformToFragment() and transformToDocument() methods.
[XSLTP]
The following terms are defined in URL: [URL]
application/x-www-form-urlencoded formatapplication/x-www-form-urlencoded serializerA number of schemes and protocols are referenced by this specification also:
The following terms are defined in the HTTP specifications: [HTTP]
Accept` headerAccept-Language` headerCache-Control` headerContent-Disposition` headerContent-Language` headerContent-Range` headerLast-Modified` headerRange` headerThe following terms are defined in HTTP State Management Mechanism: [COOKIES]
The following term is defined in Web Linking: [WEBLINK]
Link` headerThe following terms are defined in Structured Field Values for HTTP: [STRUCTURED-FIELDS]
The following terms are defined in MIME Sniffing: [MIMESNIFF]
The following terms are defined in Fetch: [FETCH]
about:blankUser-Agent` valueOrigin` headerCross-Origin-Resource-Policy` headerRequestCredentials enumerationRequestDestination enumerationfetch() methodThe following terms are defined in Referrer Policy: [REFERRERPOLICY]
Referrer-Policy` HTTP headerReferrer-Policy` header algorithmno-referrer",
"no-referrer-when-downgrade",
"origin-when-cross-origin", and
"unsafe-url" referrer policiesThe following terms are defined in Mixed Content: [MIX]
The following terms are defined in Subresource Integrity: [SRI]
The following terms are defined in Paint Timing: [PAINTTIMING]
The following terms are defined in Navigation Timing: [NAVIGATIONTIMING]
NavigationTimingType and its
"navigate",
"reload", and
"back_forward" values.The following terms are defined in Resource Timing: [RESOURCETIMING]
The following terms are defined in Performance Timeline: [PERFORMANCETIMELINE]
PerformanceEntry and its
name,
entryType,
startTime, and
duration attributes.The following terms are defined in Long Animation Frames: [LONGANIMATIONFRAMES]
The following terms are defined in Long Tasks: [LONGTASKS]
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in Web IDL. [WEBIDL]
The following terms are defined in Web IDL:
[Global][LegacyFactoryFunction][LegacyLenientThis][LegacyNullToEmptyString][LegacyOverrideBuiltIns][LegacyTreatNonObjectAsNull][LegacyUnenumerableNamedProperties][LegacyUnforgeable]Web IDL also defines the following types that are used in Web IDL fragments in this specification:
ArrayBufferArrayBufferViewbooleanDOMStringdoubleFunctionlongobjectPromiseUint8ClampedArrayunrestricted doubleunsigned longUSVStringThe term throw in this
specification is used as defined in Web IDL. The DOMException
type and the following exception names are defined by Web IDL and used by this
specification:
Some parts of the language described by this specification only support JavaScript as the underlying scripting language. [JAVASCRIPT]
The following terms are defined in the JavaScript specification and used in this specification:
Atomics objectAtomics.waitAsync objectDate classFinalizationRegistry classRegExp classSharedArrayBuffer classSyntaxError classTypeError classRangeError classWeakRef classeval() functionWeakRef.prototype.deref() functionimport()import.metatypeof operatordelete operatorUsers agents that support JavaScript must also implement the Dynamic Code Brand Checks proposal. The following terms are defined there, and used in this specification: [JSDYNAMICCODEBRANDCHECKS]
Users agents that support JavaScript must also implement ECMAScript Internationalization API. [JSINTL]
User agents that support JavaScript must also implement the Import Attributes proposal. The following terms are defined there, and used in this specification: [JSIMPORTATTRIBUTES]
User agents that support JavaScript must also implement the JSON modules proposal. The following terms are defined there, and used in this specification: [JSJSONMODULES]
User agents that support JavaScript must also implement the Resizable ArrayBuffer and growable SharedArrayBuffer proposal. The following terms are defined there, and used in this specification: [JSRESIZABLEBUFFERS]
User agents that support JavaScript must also implement the Temporal proposal. The following terms are defined there, and used in this specification: [JSTEMPORAL]
The following term is defined in WebAssembly JavaScript Interface: [WASMJS]
The Document Object Model (DOM) is a representation — a model — of a document and its content. The DOM is not just an API; the conformance criteria of HTML implementations are defined, in this specification, in terms of operations on the DOM. [DOM]
Implementations must support DOM and the events defined in UI Events, because this specification is defined in terms of the DOM, and some of the features are defined as extensions to the DOM interfaces. [DOM] [UIEVENTS]
In particular, the following features are defined in DOM: [DOM]
Attr interfaceCharacterData interfaceComment interfaceDOMImplementation interfaceDocument interface and its
doctype attribute
DocumentOrShadowRoot interfaceDocumentFragment interfaceDocumentType interfaceChildNode interfaceElement interfaceattachShadow() method.Node interfaceNodeList interfaceProcessingInstruction interfaceShadowRoot interfaceText interfaceRange interfaceHTMLCollection interface, its
length attribute, and its
item() and
namedItem() methodsDOMTokenList interface, and its
value attribute and
supports operationcreateDocument() methodcreateHTMLDocument() methodcreateElement() methodcreateElementNS() methodgetElementById() methodgetElementsByClassName() methodappend() methodappendChild() methodcloneNode() methodimportNode() methodpreventDefault() methodid attributesetAttribute() methodtextContent attributeslotchange eventCharacterData node and its
replace data algorithmEvent interfaceEvent and derived interfaces constructor behaviorEventTarget interfaceEventInit dictionary typetype attributecurrentTarget attributebubbles attributecancelable attributecomposed attributeisTrusted attributeinitEvent() methodaddEventListener() methodEventListener callback interfaceDocumentis valueMutationObserver interface and mutation observers in generalAbortController and its
signalAbortSignalThe following features are defined in UI Events: [UIEVENTS]
MouseEvent interfaceMouseEvent interface's relatedTarget attributeMouseEventInit dictionary typeFocusEvent interfaceFocusEvent interface's relatedTarget attributeUIEvent interfaceUIEvent interface's view attributeauxclick eventbeforeinput eventclick eventcontextmenu eventdblclick eventinput eventmousedown eventmouseenter eventmouseleave eventmousemove eventmouseout eventmouseover eventmouseup eventwheel eventkeydown eventkeypress eventThe following features are defined in Touch Events: [TOUCH]
Touch interfaceThe following features are defined in Pointer Events: [POINTEREVENTS]
PointerEvent interfacePointerEvent interface's pointerType attributepointerdown eventpointerup eventThe following events are defined in Clipboard API and events: [CLIPBOARD-APIS]
The following features are defined in DOM Parsing and Serialization: [DOMPARSING]
The following features are defined in Selection API: [SELECTION]
The following features are defined in Fullscreen API: [FULLSCREEN]
High Resolution Time provides the following features: [HRT]
This specification uses the following features defined in File API: [FILEAPI]
Blob interface and its
type attributeFile interface and its
name and
lastModified attributesFileList interfaceBlob's snapshot stateThe following terms are defined in Indexed Database API: [INDEXEDDB]
The following terms are defined in Media Source Extensions: [MEDIASOURCE]
MediaSource interfaceThe following terms are defined in Media Capture and Streams: [MEDIASTREAM]
MediaStream interfaceMediaStreamTrackThe following terms are defined in Reporting: [REPORTING]
The following features and terms are defined in XMLHttpRequest: [XHR]
XMLHttpRequest interface, and its
responseXML attributeProgressEvent interface, and its
lengthComputable,
loaded, and
total attributesFormData interface, and its associated
entry listThe following features are defined in Battery Status API: [BATTERY]
While support for CSS as a whole is not required of implementations of this specification (though it is encouraged, at least for web browsers), some features are defined in terms of specific CSS requirements.
The following terms and features are defined in Cascading Style Sheets (CSS): [CSS]
The following terms and features are defined in CSS Box Model: [CSSBOX]
The following features are defined in CSS Logical Properties: [CSSLOGICAL]
The following terms and features are defined in CSS Color: [CSSCOLOR]
The following terms are defined in CSS Images: [CSSIMAGES]
The following features are defined in CSS Backgrounds and Borders: [CSSBG]
CSS Backgrounds and Borders also defines the following border properties: [CSSBG]
| Top | Bottom | Left | Right | |
|---|---|---|---|---|
| Width | 'border-top-width' | 'border-bottom-width' | 'border-left-width' | |
| Style | 'border-top-style' | 'border-bottom-style' | 'border-left-style' | |
| Color | 'border-top-color' | 'border-bottom-color' | 'border-left-color' |
The following features are defined in CSS Box Alignment: [CSSALIGN]
The following terms and features are defined in CSS Display: [CSSDISPLAY]
The following features are defined in CSS Flexible Box Layout: [CSSFLEXBOX]
The following terms and features are defined in CSS Fonts: [CSSFONTS]
The following features are defined in CSS Grid Layout: [CSSGRID]
The following terms are defined in CSS Inline Layout: [CSSINLINE]
The following terms and features are defined in CSS Box Sizing: [CSSSIZING]
The following features are defined in CSS Lists and Counters. [CSSLISTS]
The following features are defined in CSS Overflow. [CSSOVERFLOW]
The following terms and features are defined in CSS Positioned Layout: [CSSPOSITION]
The following features are defined in CSS Multi-column Layout. [CSSMULTICOL]
The following features are defined in CSS Table: [CSSTABLE]
The following features are defined in CSS Text: [CSSTEXT]
The following features are defined in CSS Writing Modes: [CSSWM]
The following features are defined in CSS Basic User Interface: [CSSUI]
Implementations that support scripting must support the CSS Object Model. The following features and terms are defined in the CSSOM specifications: [CSSOM] [CSSOMVIEW]
Screen interfaceLinkStyle interfaceCSSStyleDeclaration interfacestyle IDL attributecssText attribute of CSSStyleDeclarationStyleSheet interfaceCSSStyleSheet interfaceCSSStyleSheetCSSStyleSheetresize eventscroll eventscrollend eventThe following features and terms are defined in CSS Syntax: [CSSSYNTAX]
The following terms are defined in Selectors: [SELECTORS]
The following features are defined in CSS Values and Units: [CSSVALUES]
The following features are defined in CSS View Transitions: [CSSVIEWTRANSITIONS]
ViewTransitionThe following terms are defined in the CSS Cascading and Inheritance: [CSSCASCADE]
The CanvasRenderingContext2D object's use of fonts depends on the features
described in the CSS Fonts and Font Loading specifications, including
in particular FontFace objects and the font source concept.
[CSSFONTS] [CSSFONTLOAD]
The following interfaces and terms are defined in Geometry Interfaces: [GEOMETRY]
DOMMatrix interface, and associated
m11 element,
m12 element,
m21 element,
m22 element,
m41 element, and
m42 elementDOMMatrix2DInit and
DOMMatrixInit dictionariesDOMMatrix from a dictionary
and create a DOMMatrix from a 2D dictionary
algorithms for DOMMatrix2DInit or DOMMatrixInitDOMPointInit dictionary, and associated
x and
y membersThe following terms are defined in the CSS Scoping: [CSSSCOPING]
The following terms and features are defined in CSS Color Adjustment: [CSSCOLORADJUST]
The following terms are defined in CSS Pseudo-Elements: [CSSPSEUDO]
The following terms are defined in CSS Containment: [CSSCONTAIN]
The following terms are defined in CSS Anchor Positioning: [CSSANCHOR]
The following term is defined in Intersection Observer: [INTERSECTIONOBSERVER]
The following terms are defined in Resize Observer: [RESIZEOBSERVER]
The following interfaces are defined in the WebGL specifications: [WEBGL]
WebGLRenderingContext interfaceWebGL2RenderingContext interfaceThe following interfaces are defined in WebGPU: [WEBGPU]
Implementations may support WebVTT as a text track format for subtitles, captions, metadata, etc., for media resources. [WEBVTT]
The following terms, used in this specification, are defined in WebVTT:
Finally, the following terms are defined ARIA: [ARIA]
ARIAMixin interface, with its associated
ARIAMixin getter steps and
ARIAMixin setter steps hooksThe following terms are defined in Content Security Policy: [CSP]
report-uri directiveframe-ancestors directivesandbox directiveSecurityPolicyViolationEvent interfaceThe following terms are defined in Service Workers: [SW]
The following algorithms are defined in Secure Contexts: [SECURE-CONTEXTS]
The following terms are defined in Permissions Policy: [PERMISSIONSPOLICY]
The following feature is defined in Payment Request API: [PAYMENTREQUEST]
While support for MathML as a whole is not required by this specification (though it is encouraged, at least for web browsers), certain features depend upon small parts of MathML being implemented. [MATHML]
The following features are defined in Mathematical Markup Language (MathML):
annotation-xml elementmath elementmerror elementmi elementmn elementmo elementms elementWhile support for SVG as a whole is not required by this specification (though it is encouraged, at least for web browsers), certain features depend upon parts of SVG being implemented.
User agents that implement SVG must implement the SVG 2 specification, and not any earlier revisions.
The following features are defined in the SVG 2 specification: [SVG]
SVGElement interfaceSVGImageElement interfaceSVGScriptElement interfaceSVGSVGElement interfacea elementdesc elementforeignObject elementimage elementscript elementsvg elementtitle elementuse elementThe following features are defined in Filter Effects: [FILTERS]
The following features are defined in Compositing and Blending: [COMPOSITE]
The following features are defined in Cooperative Scheduling of Background Tasks: [REQUESTIDLECALLBACK]
The following terms are defined in Screen Orientation: [SCREENORIENTATION]
The following terms are defined in Storage: [STORAGE]
The following features are defined in Web App Manifest: [MANIFEST]
The following terms are defined in WebAssembly JavaScript Interface: ESM Integration: [WASMESM]
The following features are defined in WebCodecs: [WEBCODECS]
VideoFrame interface.The following terms are defined in WebDriver: [WEBDRIVER]
The following terms are defined in WebDriver BiDi: [WEBDRIVERBIDI]
The following terms are defined in Web Cryptography API: [WEBCRYPTO]
The following terms are defined in WebSockets: [WEBSOCKETS]
The following terms are defined in WebTransport: [WEBTRANSPORT]
The following terms are defined in Web Authentication: An API for accessing Public Key Credentials: [WEBAUTHN]
The following terms are defined in Credential Management: [CREDMAN]
The following terms are defined in Console: [CONSOLE]
The following terms are defined in Web Locks API: [WEBLOCKS]
This specification uses the following features defined in Trusted Types: [TRUSTED-TYPES]
The following terms are defined in WebRTC API: [WEBRTC]
The following terms are defined in Picture-in-Picture API: [PICTUREINPICTURE]
The following terms are defined in Idle Detection API:
The following terms are defined in Web Speech API:
The following terms are defined in WebOTP API:
The following terms are defined in Web Share API:
The following terms are defined in Web Smart Card API:
The following terms are defined in Web Background Synchronization:
The following terms are defined in Web Periodic Background Synchronization:
The following terms are defined in Background Fetch:
The following terms are defined in Keyboard Lock:
The following terms are defined in Web MIDI API:
The following terms are defined in Generic Sensor API:
The following terms are defined in WebHID API:
The following terms are defined in WebXR Device API:
This specification does not require support of any particular network protocol, style sheet language, scripting language, or any of the DOM specifications beyond those required in the list above. However, the language described by this specification is biased towards CSS as the styling language, JavaScript as the scripting language, and HTTP as the network protocol, and several features assume that those languages and protocols are in use.
A user agent that implements the HTTP protocol must implement HTTP State Management Mechanism (Cookies) as well. [HTTP] [COOKIES]
Vendor-specific proprietary user agent extensions to this specification are strongly discouraged. Documents must not use such extensions, as doing so reduces interoperability and fragments the user base, allowing only users of specific user agents to access the content in question.
All extensions must be defined so that the use of extensions neither contradicts nor causes the non-conformance of functionality defined in the specification.
When vendor-neutral extensions to this specification are needed, either this specification can be updated accordingly, or an extension specification can be written that overrides the requirements in this specification. When someone applying this specification to their activities decides that they will recognize the requirements of such an extension specification, it becomes an applicable specification for the purposes of conformance requirements in this specification.
User agents must treat elements and attributes that they do not understand as semantically neutral; leaving them in the DOM (for DOM processors), and styling them according to CSS (for CSS processors), but not inferring any meaning from them.
When support for a feature is disabled (e.g. as an emergency measure to mitigate a security problem, or to aid in development, or for performance reasons), user agents must act as if they had no support for the feature whatsoever, and as if the feature was not mentioned in this specification. For example, if a particular feature is accessed via an attribute in a Web IDL interface, the attribute itself would be omitted from the objects that implement that interface — leaving the attribute on the object but making it return null or throw an exception is insufficient.
Implementations of XPath 1.0 that operate on HTML
documents parsed or created in the manners described in this specification (e.g. as part of
the document.evaluate() API) must act as if the following edit was applied
to the XPath 1.0 specification.
First, remove this paragraph:
A QName in the node test is expanded into an expanded-name using the namespace declarations from the expression context. This is the same way expansion is done for element type names in start and end-tags except that the default namespace declared with
xmlnsis not used: if the QName does not have a prefix, then the namespace URI is null (this is the same way attribute names are expanded). It is an error if the QName has a prefix for which there is no namespace declaration in the expression context.
Then, insert in its place the following:
A QName in the node test is expanded into an expanded-name using the namespace declarations from the expression context. If the QName has a prefix, then there must be a namespace declaration for this prefix in the expression context, and the corresponding namespace URI is the one that is associated with this prefix. It is an error if the QName has a prefix for which there is no namespace declaration in the expression context.
If the QName has no prefix and the principal node type of the axis is element, then the default element namespace is used. Otherwise, if the QName has no prefix, the namespace URI is null. The default element namespace is a member of the context for the XPath expression. The value of the default element namespace when executing an XPath expression through the DOM3 XPath API is determined in the following way:
- If the context node is from an HTML DOM, the default element namespace is "http://www.w3.org/1999/xhtml".
- Otherwise, the default element namespace URI is null.
XSLT 1.0 processors outputting to a DOM when the output method is "html" (either explicitly or via the defaulting rule in XSLT 1.0) are affected as follows:
If the transformation program outputs an element in no namespace, the processor must, prior to constructing the corresponding DOM element node, change the namespace of the element to the HTML namespace, ASCII-lowercase the element's local name, and ASCII-lowercase the names of any non-namespaced attributes on the element.
This specification does not specify precisely how XSLT processing interacts with the HTML
parser infrastructure (for example, whether an XSLT processor acts as if it puts any
elements into a stack of open elements). However, XSLT processors must stop
parsing if they successfully complete, and must update the current document
readiness first to "interactive" and then to "complete" if they are aborted.
This specification does not specify how XSLT interacts with the navigation algorithm, how it fits in with the event loop, nor how error pages are to be handled (e.g. whether XSLT errors are to replace an incremental XSLT output, or are rendered inline, etc.).
Headers/Permissions-Policy/document-domain
Support in one engine only.
This document defines the following policy-controlled features:
Headers/Feature-Policy/autoplay
Headers/Permissions-Policy/autoplay
Support in one engine only.
autoplay", which has a default allowlist of 'self'.There are various places in HTML that accept particular data types, such as dates or numbers. This section describes what the conformance criteria for content in those formats is, and how to parse them.
Some of the micro-parsers described below follow the pattern of having an input variable that holds the string being parsed, and having a position variable pointing at the next character to parse in input.
If the attribute is present, its value must either be the empty string or a value that is an ASCII case-insensitive match for the attribute's canonical name, with no leading or trailing whitespace.
Some attributes, called enumerated attributes, take on a finite set of states. The state for such an attribute is derived by combining the attribute's value, a set of keyword/state mappings given in the specification of each attribute, and two possible special states that can also be given in the specification of the attribute. These special states are the invalid value default and the missing value default.
To determine the state of an attribute, use the following steps:
If the attribute is not specified:
If the attribute has a missing value default state defined, then return that missing value default state.
Otherwise, return no state.
If the attribute's value is an ASCII case-insensitive match for one of the keywords defined for the attribute, then return the state represented by that keyword.
If the attribute has an invalid value default state defined, then return that invalid value default state.
Return no state.
For authoring conformance purposes, if an enumerated attribute is specified, the attribute's value must be an ASCII case-insensitive match for one of the conforming keywords for that attribute, with no leading or trailing whitespace.
A valid integer without a U+002D HYPHEN-MINUS (-) prefix represents the number that is represented in base ten by that string of digits. A valid integer with a U+002D HYPHEN-MINUS (-) prefix represents the number represented in base ten by the string of digits that follows the U+002D HYPHEN-MINUS, subtracted from zero.
A valid non-negative integer represents the number that is represented in base ten by that string of digits.
A valid floating-point number represents the number obtained by multiplying the significand by ten raised to the power of the exponent, where the significand is the first number, interpreted as base ten (including the decimal point and the number after the decimal point, if any, and interpreting the significand as a negative number if the whole string starts with a U+002D HYPHEN-MINUS character (-) and the number is not zero), and where the exponent is the number after the E, if any (interpreted as a negative number if there is a U+002D HYPHEN-MINUS character (-) between the E and the number and the number is not zero, or else ignoring a U+002B PLUS SIGN character (+) between the E and the number if there is one). If there is no E, then the exponent is treated as zero.
When ASCII digits are used in the date and time syntaxes defined in this section, they express numbers in base ten.
Where this specification refers to the proleptic Gregorian calendar, it means the modern Gregorian calendar, extrapolated backwards to year 1. A date in the proleptic Gregorian calendar, sometimes explicitly referred to as a proleptic-Gregorian date, is one that is described using that calendar even if that calendar was not in use at the time (or place) in question. [GREGORIAN]
Times in dates before the formation of UTC in the mid-twentieth century must be expressed and interpreted in terms of UT1 (contemporary Earth solar time at the 0° longitude), not UTC (the approximation of UT1 that ticks in SI seconds). Time before the formation of time zones must be expressed and interpreted as UT1 times with explicit time zones that approximate the contemporary difference between the appropriate local time and the time observed at the location of Greenwich, London.
A week-year with a number year has 53 weeks if it corresponds to either a year year in the proleptic Gregorian calendar that has a Thursday as its first day (January 1st), or a year year in the proleptic Gregorian calendar that has a Wednesday as its first day (January 1st) and where year is a number divisible by 400, or a number divisible by 4 but not by 100. All other week-years have 52 weeks.
A string containing a set of space-separated tokens may have leading or trailing ASCII whitespace.
Sets of space-separated tokens sometimes have a defined set of allowed values. When a set of allowed values is defined, the tokens must all be from that list of allowed values; other values are non-conforming. If no such set of allowed values is provided, then all values are conforming.
Sets of comma-separated tokens sometimes have further restrictions on what consists a valid token. When such restrictions are defined, the tokens must all fit within those restrictions; other values are non-conforming. If no such restrictions are specified, then all values are conforming.
A string matches the environment of the user if it is the empty string, a string consisting of only ASCII whitespace, or is a media query list that matches the user's environment according to the definitions given in Media Queries. [MQ]
To create a new unique internal value, return a unique internal value that has never previously been returned by this algorithm.
A URL matches about:srcdoc if its scheme is "about", its path contains a single string "srcdoc",
its query is null, its username and password are the empty string, and its host is null.
Parsing a URL is the process of taking a string and obtaining the URL record that it represents. While this process is defined in URL, the HTML standard defines several wrappers to abstract base URLs and encodings. [URL]
When a document's document base URL changes, all elements in that document are affected by a base URL change.
The following are base URL change steps, which run when an element is affected by a base URL change (as defined by DOM):
If the URL identified by the hyperlink is being shown to the user, or if any
data derived from that URL is affecting the display, then the href attribute's value should be reparsed, relative to the element's node
document and the UI updated appropriately.
If the hyperlink has a ping attribute and its
URL(s) are being shown to the user, then the ping attribute's tokens should be reparsed, relative to the element's node
document and the UI updated appropriately.
q, blockquote, ins, or
del element with a cite attributeIf the URL identified by the cite attribute is being
shown to the user, or if any data derived from that URL is affecting the display,
then the cite attribute's value should be reparsed, relative to the element's node document and the UI updated
appropriately.
The element is not directly affected.
The rules for sniffing images specifically, the rules for distinguishing if a resource is text or binary, and the rules for sniffing audio and video specifically are also defined in MIME Sniffing. These rules return a MIME type as their result. [MIMESNIFF]
meta elementsSupport in all current engines.
A CORS settings attribute is an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
anonymous
| Anonymous | Requests for the element will have their
mode set to "cors" and their
credentials mode set to "same-origin".
|
| (the empty string) | ||
use-credentials
| Use Credentials | Requests for the element will have their mode set to "cors" and their credentials mode set to "include".
|
The majority of fetches governed by CORS settings attributes will be done via the create a potential-CORS request algorithm.
The attribute's missing value default and invalid value default are both the empty string state.
The impact of these states on the processing model of various fetches is defined in more detail throughout this specification, in Fetch, and in Referrer Policy. [FETCH] [REFERRERPOLICY]
Support in all current engines.
Elements that have a nonce content attribute ensure that the
cryptographic nonce is only exposed to script (and not to side-channels like CSS attribute
selectors) by taking the value from the content attribute, moving it into an internal slot
named [[CryptographicNonce]], exposing it to script
via the HTMLOrSVGElement interface mixin, and setting the content attribute to the
empty string. Unless otherwise specified, the slot's value is the empty string.
The following attribute change
steps are used for the nonce content attribute:
If element does not include HTMLOrSVGElement, then
return.
If localName is not nonce or
namespace is not null, then return.
If value is null, then set element's [[CryptographicNonce]] to the empty string.
Otherwise, set element's [[CryptographicNonce]] to value.
Whenever an element including HTMLOrSVGElement
becomes browsing-context connected, the user agent must execute the following steps
on the element:
Let CSP list be element's shadow-including root's policy container's CSP list.
If CSP list contains a header-delivered Content Security Policy, and
element has a nonce content attribute
attr whose value is not the empty string, then:
Let nonce be element's [[CryptographicNonce]].
Set an attribute value for
element using "nonce" and the empty
string.
Set element's [[CryptographicNonce]] to nonce.
The cloning steps for elements that
include HTMLOrSVGElement given node, copy, and
subtree are to set copy's [[CryptographicNonce]] to
node's [[CryptographicNonce]].
Support in all current engines.
A lazy loading attribute is an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
lazy
| Lazy | Used to defer fetching a resource until some conditions are met. |
eager
| Eager | Used to fetch a resource immediately; the default state. |
The attribute directs the user agent to fetch a resource immediately or to defer fetching until some conditions associated with the element are met, according to the attribute's current state.
The attribute's missing value default and invalid value default are both the Eager state.
A blocking attribute explicitly indicates that certain operations should be blocked on the fetching of an external resource. The operations that can be blocked are represented by possible blocking tokens, which are strings listed by the following table:
| Possible blocking token | Description |
|---|---|
"render"
| The element is potentially render-blocking. |
A blocking attribute must have a value that is an unordered set of unique space-separated tokens, each of which are possible blocking tokens. The supported tokens of a blocking attribute are the possible blocking tokens. Any element can have at most one blocking attribute.
An element is potentially render-blocking if its blocking tokens set
contains "render", or if it is
implicitly potentially render-blocking, which will be defined at the individual
elements. By default, an element is not implicitly potentially render-blocking.
A fetch priority attribute is an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
high
| high | Signals a high-priority fetch relative to other resources with the same destination. |
low
| low | Signals a low-priority fetch relative to other resources with the same destination. |
auto
| auto | Signals automatic determination of fetch priority relative to other resources with the same destination. |
The attribute's missing value default and invalid value default are both the auto state.
The building blocks for reflecting are as follows:
Reflected targets have these associated algorithms:
For a reflected target that is an element element, these are defined as follows:
Return element.
Let attribute be the result of running get an attribute by namespace and local name given null, the reflected content attribute name, and element.
If attribute is null, then return null.
Return attribute's value.
Set an attribute value given element, the reflected content attribute name, and value.
Remove an attribute by namespace and local name given null, the reflected content attribute name, and element.
For a reflected target that is an ElementInternals object
elementInternals, they are defined as follows:
Return elementInternals's target element.
If elementInternals's target element's internal content attribute map[the reflected content attribute name] does not exist, then return null.
Return elementInternals's target element's internal content attribute map[the reflected content attribute name].
Set elementInternals's target element's internal content attribute map[the reflected content attribute name] to value.
Remove elementInternals's target element's internal content attribute map[the reflected content attribute name].
If a reflected IDL attribute has the type DOMString:
The getter steps are:
Let element be the result of running this's get the element.
Let contentAttributeValue be the result of running this's get the content attribute.
Let attributeDefinition be the attribute definition of element's content attribute whose namespace is null and local name is the reflected content attribute name.
If attributeDefinition indicates it is an enumerated attribute and the reflected IDL attribute is defined to be limited to only known values:
If contentAttributeValue does not correspond to any state of attributeDefinition (e.g., it is null and there is no missing value default), or if it is in a state of attributeDefinition with no associated keyword value, then return the empty string.
Return the canonical keyword for the state of attributeDefinition that contentAttributeValue corresponds to.
If contentAttributeValue is null, then return the empty string.
Return contentAttributeValue.
The setter steps are to run this's set the content attribute with the given value.
If a reflected IDL attribute has the type DOMString?:
The getter steps are:
Let element be the result of running this's get the element.
Let contentAttributeValue be the result of running this's get the content attribute.
Let attributeDefinition be the attribute definition of element's content attribute whose namespace is null and local name is the reflected content attribute name.
Assert: attributeDefinition indicates it is an enumerated attribute.
Assert: the reflected IDL attribute is limited to only known values.
Assert: contentAttributeValue corresponds to a state of attributeDefinition.
If contentAttributeValue corresponds to a state of attributeDefinition with no associated keyword value, then return null.
Return the canonical keyword for the state of attributeDefinition that contentAttributeValue corresponds to.
The setter steps are:
If the given value is null, then run this's delete the content attribute.
Otherwise, run this's set the content attribute with the given value.
If a reflected IDL attribute has the type USVString:
The getter steps are:
Let element be the result of running this's get the element.
Let contentAttributeValue be the result of running this's get the content attribute.
Let attributeDefinition be the attribute definition of element's content attribute whose namespace is null and local name is the reflected content attribute name.
If attributeDefinition indicates it contains a URL:
If contentAttributeValue is null, then return the empty string.
Let urlString be the result of encoding-parsing-and-serializing a URL given contentAttributeValue, relative to element's node document.
If urlString is not failure, then return urlString.
Return contentAttributeValue, converted to a scalar value string.
The setter steps are to run this's set the content attribute with the given value.
If a reflected IDL attribute has the type boolean:
The getter steps are:
Let contentAttributeValue be the result of running this's get the content attribute.
If contentAttributeValue is null, then return false.
Return true.
The setter steps are:
If the given value is false, then run this's delete the content attribute.
If the given value is true, then run this's set the content attribute with the empty string.
If a reflected IDL attribute has the type long,
optionally limited to only non-negative numbers and optionally with a default
value defaultValue:
The getter steps are:
Let contentAttributeValue be the result of running this's get the content attribute.
If contentAttributeValue is not null:
Let parsedValue be the result of integer parsing contentAttributeValue if the reflected IDL attribute is not limited to only non-negative numbers; otherwise the result of non-negative integer parsing contentAttributeValue.
If parsedValue is not an error and is within the long range, then return parsedValue.
If the reflected IDL attribute has a default value, then return defaultValue.
If the reflected IDL attribute is limited to only non-negative numbers, then return −1.
Return 0.
The setter steps are:
If the reflected IDL attribute is limited to only non-negative
numbers and the given value is negative, then throw an
"IndexSizeError" DOMException.
Run this's set the content attribute with the given value converted to the shortest possible string representing the number as a valid integer.
If a reflected IDL attribute has the type unsigned long, optionally limited to only positive
numbers, limited to only positive
numbers with fallback, or clamped to the range [clampedMin,
clampedMax], and optionally with a default value defaultValue:
The getter steps are:
Let contentAttributeValue be the result of running this's get the content attribute.
Let minimum be 0.
If the reflected IDL attribute is limited to only positive numbers or limited to only positive numbers with fallback, then set minimum to 1.
If the reflected IDL attribute is clamped to the range, then set minimum to clampedMin.
Let maximum be 2147483647 if the reflected IDL attribute is not clamped to the range; otherwise clampedMax.
If contentAttributeValue is not null:
Let parsedValue be the result of non-negative integer parsing contentAttributeValue.
If parsedValue is not an error and is in the range minimum to maximum, inclusive, then return parsedValue.
If parsedValue is not an error and the reflected IDL attribute is clamped to the range:
If parsedValue is less than minimum, then return minimum.
Return maximum.
If the reflected IDL attribute has a default value, then return defaultValue.
Return minimum.
The setter steps are:
If the reflected IDL attribute is limited to only positive
numbers and the given value is 0, then throw an
"IndexSizeError" DOMException.
Let minimum be 0.
If the reflected IDL attribute is limited to only positive numbers or limited to only positive numbers with fallback, then set minimum to 1.
Let newValue be minimum.
If the reflected IDL attribute has a default value, then set newValue to defaultValue.
If the given value is in the range minimum to 2147483647, inclusive, then set newValue to it.
Run this's set the content attribute with newValue converted to the shortest possible string representing the number as a valid non-negative integer.
If a reflected IDL attribute has the type double,
optionally limited to only positive numbers
and optionally with a default value defaultValue:
The getter steps are:
Let contentAttributeValue be the result of running this's get the content attribute.
If contentAttributeValue is not null:
Let parsedValue be the result of floating-point number parsing contentAttributeValue.
If parsedValue is not an error and is greater than 0, then return parsedValue.
If parsedValue is not an error and the reflected IDL attribute is not limited to only positive numbers, then return parsedValue.
If the reflected IDL attribute has a default value, then return defaultValue.
Return 0.
The setter steps are:
If the reflected IDL attribute is limited to only positive numbers and the given value is not greater than 0, then return.
Run this's set the content attribute with the given value, converted to the best representation of the number as a floating-point number.
If a reflected IDL attribute has the type DOMTokenList, then its
getter steps are to return a DOMTokenList object whose associated element is
this and associated attribute's local name is the reflected content
attribute name. Specification authors cannot use support
ElementInternals for IDL attributes of this type.
If a reflected IDL attribute has the type T?,
where T is either Element or an interface that inherits from
Element, then with attr being the reflected content attribute
name:
The getter steps are to return the result of running this's get the attr-associated element.
The setter steps are:
If the given value is null, then:
Set this's explicitly set attr-element to null.
Run this's delete the content attribute.
Return.
Run this's set the content attribute with the empty string.
Set this's explicitly set attr-element to a weak reference to the given value.
For element reflected targets only: the following attribute change steps, given element, localName, oldValue, value, and namespace, are used to synchronize between the content attribute and the IDL attribute:
If localName is not attr or namespace is not null, then return.
Set element's explicitly set attr-element to null.
If a reflected IDL attribute has the type FrozenArray<T>?, where T is either
Element or an interface that inherits from Element, then with
attr being the reflected content attribute name:
The getter steps are:
Let elements be the result of running this's get the attr-associated elements.
If the contents of elements is equal to the contents of this's cached attr-associated elements, then return this's cached attr-associated elements object.
Let elementsAsFrozenArray be elements, converted to a FrozenArray<T>?.
Set this's cached attr-associated elements to elements.
Set this's cached attr-associated elements object to elementsAsFrozenArray.
Return elementsAsFrozenArray.
The setter steps are:
If the given value is null:
Set this's explicitly set attr-elements to null.
Run this's delete the content attribute.
Return.
Run this's set the content attribute with the empty string.
Let elements be an empty list.
For each element in the given value:
Append a weak reference to element to elements.
Set this's explicitly set attr-elements to elements.
For element reflected targets only: the following attribute change steps, given element, localName, oldValue, value, and namespace, are used to synchronize between the content attribute and the IDL attribute:
If localName is not attr or namespace is not null, then return.
Set element's explicitly set attr-elements to null.
Reflection is primarily about improving web developer ergonomics by giving them typed access to content attributes through reflected IDL attributes. The ultimate source of truth, which the web platform builds upon, is the content attributes themselves. That is, specification authors must not use the reflected IDL attribute getter or setter steps, but instead must use the content attribute presence and value. (Or an abstraction on top, such as the state of an enumerated attribute.)
Two important exceptions to this are reflected IDL attributes whose type is one of the following:
T?, where T is either Element or
an interface that inherits from Element
FrozenArray<T>?, where T is either
Element or an interface that inherits from Element
For those, specification authors must use the reflected target's get the attr-associated element and get the attr-associated elements, respectively. The content attribute presence and value must not be used as they cannot be fully synchronized with the reflected IDL attribute.
A reflected target's explicitly set attr-element, explicitly set attr-elements, cached attr-associated elements, and cached attr-associated elements object are to be treated as internal implementation details and not to be built upon.
The HTMLFormControlsCollection and HTMLOptionsCollection interfaces
are collections derived from the
HTMLCollection interface. The HTMLAllCollection interface is a collection, but is not so derived.
HTMLAllCollection interfaceThe HTMLAllCollection interface is used for the legacy document.all attribute. It operates similarly to
HTMLCollection; the main differences are that it allows a staggering variety of
different (ab)uses of its methods to all end up returning something, and that it can be called as
a function as an alternative to property access.
Objects that implement the HTMLAllCollection interface are legacy platform objects with an additional [[Call]] internal
method described in the section below. They also have an
[[IsHTMLDDA]] internal slot.
The object's supported property indices are as defined for
HTMLCollection objects.
The supported property names consist of the non-empty values of all the id attributes of all the elements represented by the
collection, and the non-empty values of all the name attributes of
all the "all"-named elements represented by the collection, in
tree order, ignoring later duplicates, with the id of
an element preceding its name if it contributes both, they differ from
each other, and neither is the duplicate of an earlier entry.
The indexed property getter must return the result of getting the "all"-indexed element from this given the passed index.
If argumentsList's size is zero, or if argumentsList[0] is undefined, return null.
Let nameOrIndex be the result of converting argumentsList[0] to a DOMString.
Let result be the result of getting the "all"-indexed or named element(s)
from this HTMLAllCollection given nameOrIndex.
Return the result of converting result to an ECMAScript value.
HTMLFormControlsCollection interfaceThe HTMLFormControlsCollection interface is used for
collections of listed
elements in form elements.
Support in all current engines.
Support in all current engines.
The object's supported property indices are as defined for
HTMLCollection objects.
The supported property names consist of the non-empty values of all the id and name attributes of all the
elements represented by the collection, in tree order, ignoring later
duplicates, with the id of an element preceding its name if it contributes both, they differ from each other, and neither is the
duplicate of an earlier entry.
Members of the RadioNodeList interface inherited from the NodeList
interface must behave as they would on a NodeList object.
Support in all current engines.
On setting, the value IDL attribute must run the
following steps:
If the new value is the string "on": let element be the first element in tree order
represented by the RadioNodeList object that is an input element whose
type attribute is in the Radio Button state and whose value content attribute is either absent, or present and equal to the new value, if any. If no such element exists, then instead let element be null.
Otherwise: let element be the first element in tree order
represented by the RadioNodeList object that is an input element whose
type attribute is in the Radio Button state and whose value content attribute is present and equal to the new value, if
any. If no such element exists, then instead let element be null.
If element is not null, then set its checkedness to true.
HTMLOptionsCollection interfaceSupport in all current engines.
The HTMLOptionsCollection interface is used for collections of option elements. It is always
rooted on a select element and has attributes and methods that manipulate that
element's descendants.
The object's supported property indices are as defined for
HTMLCollection objects.
The length setter steps are:
Let current be the number of nodes represented by the collection.
If the given value is greater than current, then:
If the given value is less than current, then:
Let n be current − value.
Remove the last n nodes in the collection from their parent nodes.
The supported property names consist of the non-empty values of all the id and name attributes of all the
elements represented by the collection, in tree order, ignoring later
duplicates, with the id of an element preceding its name if it contributes both, they differ from each other, and neither is
the duplicate of an earlier entry.
When the user agent is to set the value of a new indexed property or set the value of an existing indexed property for a given property index index to a new value value, it must run the following algorithm:
If value is null, invoke the steps for the remove method with index as
the argument, and return.
Let length be the number of nodes represented by the collection.
Let n be index minus length.
If n is greater than zero, then append a DocumentFragment consisting of n-1 new option elements with no attributes and
no child nodes to the select element on which the HTMLOptionsCollection
is rooted.
If n is greater than or equal to zero, append value to the select
element. Otherwise, replace the indexth element in the collection by value.
The selectedIndex IDL attribute must act
like the identically named attribute on the select element on which the
HTMLOptionsCollection is rooted
DOMStringList interfaceSupport in all current engines.
The DOMStringList interface is a non-fashionable retro way of representing a list
of strings.
Each DOMStringList object has an associated list.
The DOMStringList interface supports indexed properties. The
supported property indices are the indices of this's
associated list.
Support in all current engines.
The length getter steps are to return
this's associated list's size.
Support in all current engines.
The item(index) method steps are to
return the indexth item in this's associated list, or null if
index plus one is greater than this's associated list's size.
Support in all current engines.
The contains(string) method steps
are to return true if this's associated list contains string, and false otherwise.
To support passing JavaScript objects,
including platform objects, across realm
boundaries, this specification defines the following infrastructure for
serializing and deserializing objects, including in some cases transferring the underlying data
instead of copying it. Collectively this serialization/deserialization process is known as
"structured cloning", although most APIs perform separate serialization and deserialization steps.
(With the notable exception being the structuredClone()
method.)
This section uses the terminology and typographic conventions from the JavaScript specification. [JAVASCRIPT]
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
/developer.mozilla.org/en-US/docs/Glossary/Serializable_object
Serializable objects support being serialized, and later deserialized, in a way that is independent of any given realm. This allows them to be stored on disk and later restored, or cloned across agent and even agent cluster boundaries.
Not all objects are serializable objects, and not all aspects of objects that are serializable objects are necessarily preserved when they are serialized.
It is up to the definition of individual platform objects to determine what data is serialized and deserialized by these steps. Typically the steps are very symmetric.
The [Serializable] extended attribute must take no
arguments, and must only appear on an interface. It must not appear more than once on an
interface.
For a given platform object, only the object's primary interface is
considered during the (de)serialization process. Thus, if inheritance is involved in defining the
interface, each [Serializable]-annotated interface in the
inheritance chain needs to define standalone serialization steps and
deserialization steps, including taking into account any important data that might
come from inherited interfaces.
Objects defined in the JavaScript specification are handled by the StructuredSerialize abstract operation directly.
Transferable objects support being transferred across agents. Transferring is effectively recreating the object while sharing a reference to the underlying data and then detaching the object being transferred. This is useful to transfer ownership of expensive resources. Not all objects are transferable objects and not all aspects of objects that are transferable objects are necessarily preserved when transferred.
It is up to the definition of individual platform objects to determine what data is transferred by these steps. Typically the steps are very symmetric.
The [Transferable] extended attribute must take no
arguments, and must only appear on an interface. It must not appear more than once on an
interface.
For a given platform object, only the object's primary interface is
considered during the transferring process. Thus, if inheritance is involved in defining the
interface, each [Transferable]-annotated interface in the
inheritance chain needs to define standalone transfer steps and
transfer-receiving steps, including taking into account any important data that might
come from inherited interfaces.
Objects defined in the JavaScript specification are handled by the StructuredSerializeWithTransfer abstract operation directly.
The StructuredSerializeInternal abstract operation takes as input a JavaScript value value and serializes it to a realm-independent form, represented here as a Record. This serialized form has all the information necessary to later deserialize into a new JavaScript value in a different realm.
This process can throw an exception, for example when trying to serialize un-serializable objects.
If memory was not supplied, let memory be an empty map.
If memory[value] exists, then return memory[value].
Let deep be false.
If value is undefined, null, a Boolean, a Number, a BigInt, or a String, then return { [[Type]]: "primitive", [[Value]]: value }.
If value is a Symbol, then throw a
"DataCloneError" DOMException.
Let serialized be an uninitialized value.
If value has a [[BooleanData]] internal slot, then set serialized to { [[Type]]: "Boolean", [[BooleanData]]: value.[[BooleanData]] }.
Otherwise, if value has a [[NumberData]] internal slot, then set serialized to { [[Type]]: "Number", [[NumberData]]: value.[[NumberData]] }.
Otherwise, if value has a [[BigIntData]] internal slot, then set serialized to { [[Type]]: "BigInt", [[BigIntData]]: value.[[BigIntData]] }.
Otherwise, if value has a [[StringData]] internal slot, then set serialized to { [[Type]]: "String", [[StringData]]: value.[[StringData]] }.
Otherwise, if value has a [[DateValue]] internal slot, then set serialized to { [[Type]]: "Date", [[DateValue]]: value.[[DateValue]] }.
Otherwise, if value has a [[RegExpMatcher]] internal slot, then set serialized to { [[Type]]: "RegExp", [[RegExpMatcher]]: value.[[RegExpMatcher]], [[OriginalSource]]: value.[[OriginalSource]], [[OriginalFlags]]: value.[[OriginalFlags]] }.
Otherwise, if value has an [[ArrayBufferData]] internal slot, then:
If IsSharedArrayBuffer(value) is true, then:
If the current settings object's cross-origin isolated
capability is false, then throw a "DataCloneError"
DOMException.
If forStorage is true, then throw a
"DataCloneError" DOMException.
If value has an [[ArrayBufferMaxByteLength]] internal slot, then set serialized to { [[Type]]: "GrowableSharedArrayBuffer", [[ArrayBufferData]]: value.[[ArrayBufferData]], [[ArrayBufferByteLengthData]]: value.[[ArrayBufferByteLengthData]], [[ArrayBufferMaxByteLength]]: value.[[ArrayBufferMaxByteLength]], [[AgentCluster]]: the surrounding agent's agent cluster }.
Otherwise, set serialized to { [[Type]]: "SharedArrayBuffer", [[ArrayBufferData]]: value.[[ArrayBufferData]], [[ArrayBufferByteLength]]: value.[[ArrayBufferByteLength]], [[AgentCluster]]: the surrounding agent's agent cluster }.
Otherwise:
If IsDetachedBuffer(value) is true, then throw a
"DataCloneError" DOMException.
Let size be value.[[ArrayBufferByteLength]].
Let dataCopy be ? CreateByteDataBlock(size).
Perform CopyDataBlockBytes(dataCopy, 0, value.[[ArrayBufferData]], 0, size).
If value has an [[ArrayBufferMaxByteLength]] internal slot, then set serialized to { [[Type]]: "ResizableArrayBuffer", [[ArrayBufferData]]: dataCopy, [[ArrayBufferByteLength]]: size, [[ArrayBufferMaxByteLength]]: value.[[ArrayBufferMaxByteLength]] }.
Otherwise, set serialized to { [[Type]]: "ArrayBuffer", [[ArrayBufferData]]: dataCopy, [[ArrayBufferByteLength]]: size }.
Otherwise, if value has a [[ViewedArrayBuffer]] internal slot, then:
If IsArrayBufferViewOutOfBounds(value) is true, then throw a
"DataCloneError" DOMException.
Let buffer be the value of value's [[ViewedArrayBuffer]] internal slot.
Let bufferSerialized be ? StructuredSerializeInternal(buffer, forStorage, memory).
Assert: bufferSerialized.[[Type]] is "ArrayBuffer", "ResizableArrayBuffer", "SharedArrayBuffer", or "GrowableSharedArrayBuffer".
If value has a [[DataView]] internal slot, then set serialized to { [[Type]]: "ArrayBufferView", [[Constructor]]: "DataView", [[ArrayBufferSerialized]]: bufferSerialized, [[ByteLength]]: value.[[ByteLength]], [[ByteOffset]]: value.[[ByteOffset]] }.
Otherwise:
Assert: value has a [[TypedArrayName]] internal slot.
Set serialized to { [[Type]]: "ArrayBufferView", [[Constructor]]: value.[[TypedArrayName]], [[ArrayBufferSerialized]]: bufferSerialized, [[ByteLength]]: value.[[ByteLength]], [[ByteOffset]]: value.[[ByteOffset]], [[ArrayLength]]: value.[[ArrayLength]] }.
Otherwise, if value has [[MapData]] internal slot, then:
Set serialized to { [[Type]]: "Map", [[MapData]]: a new empty List }.
Set deep to true.
Otherwise, if value has [[SetData]] internal slot, then:
Set serialized to { [[Type]]: "Set", [[SetData]]: a new empty List }.
Set deep to true.
Otherwise, if value has an [[ErrorData]] internal slot and value is not a platform object, then:
Let name be ? Get(value, "name").
If name is not one of "Error", "EvalError", "RangeError", "ReferenceError", "SyntaxError", "TypeError", or "URIError", then set name to "Error".
Let valueMessageDesc be ? value.[[GetOwnProperty]]("message").
Let message be undefined if IsDataDescriptor(valueMessageDesc) is false, and ? ToString(valueMessageDesc.[[Value]]) otherwise.
Set serialized to { [[Type]]: "Error", [[Name]]: name, [[Message]]: message }.
User agents should attach a serialized representation of any interesting accompanying
data which are not yet specified, notably the stack property, to
serialized.
Otherwise, if value is an Array exotic object, then:
Let valueLenDescriptor be ?
OrdinaryGetOwnProperty(value, "length").
Let valueLen be valueLenDescriptor.[[Value]].
Set serialized to { [[Type]]: "Array", [[Length]]: valueLen, [[Properties]]: a new empty List }.
Set deep to true.
Otherwise, if value is a platform object that is a serializable object:
If value has a [[Detached]] internal slot whose value is true,
then throw a "DataCloneError" DOMException.
Let typeString be the identifier of the primary interface of value.
Set serialized to { [[Type]]: typeString }.
Set deep to true.
Otherwise, if value is a platform object, then throw a
"DataCloneError" DOMException.
Otherwise, if IsCallable(value) is true, then throw a
"DataCloneError" DOMException.
Otherwise, if value has any internal slot other than [[Prototype]],
[[Extensible]], or [[PrivateElements]], then throw a "DataCloneError"
DOMException.
Otherwise, if value is an exotic object and value is not the
%Object.prototype% intrinsic object associated with any realm, then
throw a "DataCloneError" DOMException.
Otherwise:
Set serialized to { [[Type]]: "Object", [[Properties]]: a new empty List }.
Set deep to true.
Set memory[value] to serialized.
If deep is true, then:
If value has a [[MapData]] internal slot, then:
Let copiedList be a new empty List.
For each Record { [[Key]], [[Value]] } entry of value.[[MapData]]:
For each Record { [[Key]], [[Value]] } entry of copiedList:
Let serializedKey be ? StructuredSerializeInternal(entry.[[Key]], forStorage, memory).
Let serializedValue be ? StructuredSerializeInternal(entry.[[Value]], forStorage, memory).
Append { [[Key]]: serializedKey, [[Value]]: serializedValue } to serialized.[[MapData]].
Otherwise, if value has a [[SetData]] internal slot, then:
Let copiedList be a new empty List.
For each entry of value.[[SetData]]:
If entry is not the special value empty, append entry to copiedList.
For each entry of copiedList:
Let serializedEntry be ? StructuredSerializeInternal(entry, forStorage, memory).
Append serializedEntry to serialized.[[SetData]].
Otherwise, if value is a platform object that is a serializable object, then perform the serialization steps for value's primary interface, given value, serialized, and forStorage.
Otherwise, for each key in ! EnumerableOwnProperties(value, key):
If ! HasOwnProperty(value, key) is true, then:
Let inputValue be ? value.[[Get]](key, value).
Let outputValue be ? StructuredSerializeInternal(inputValue, forStorage, memory).
Append { [[Key]]: key, [[Value]]: outputValue } to serialized.[[Properties]].
Return serialized.
The StructuredDeserialize abstract operation takes as input a Record serialized, which was previously produced by StructuredSerialize or StructuredSerializeForStorage, and deserializes it into a new JavaScript value, created in targetRealm.
This process can throw an exception, for example when trying to allocate memory for the new
objects (especially ArrayBuffer objects).
If memory was not supplied, let memory be an empty map.
If memory[serialized] exists, then return memory[serialized].
Let deep be false.
Let value be an uninitialized value.
If serialized.[[Type]] is "primitive", then set value to serialized.[[Value]].
Otherwise, if serialized.[[Type]] is "Boolean", then set value to a new Boolean object in targetRealm whose [[BooleanData]] internal slot value is serialized.[[BooleanData]].
Otherwise, if serialized.[[Type]] is "Number", then set value to a new Number object in targetRealm whose [[NumberData]] internal slot value is serialized.[[NumberData]].
Otherwise, if serialized.[[Type]] is "BigInt", then set value to a new BigInt object in targetRealm whose [[BigIntData]] internal slot value is serialized.[[BigIntData]].
Otherwise, if serialized.[[Type]] is "String", then set value to a new String object in targetRealm whose [[StringData]] internal slot value is serialized.[[StringData]].
Otherwise, if serialized.[[Type]] is "Date", then set value to a new Date object in targetRealm whose [[DateValue]] internal slot value is serialized.[[DateValue]].
Otherwise, if serialized.[[Type]] is "RegExp", then set value to a new RegExp object in targetRealm whose [[RegExpMatcher]] internal slot value is serialized.[[RegExpMatcher]], whose [[OriginalSource]] internal slot value is serialized.[[OriginalSource]], and whose [[OriginalFlags]] internal slot value is serialized.[[OriginalFlags]].
Otherwise, if serialized.[[Type]] is "SharedArrayBuffer", then:
If targetRealm's corresponding agent cluster is not
serialized.[[AgentCluster]], then throw a
"DataCloneError" DOMException.
Otherwise, set value to a new SharedArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is serialized.[[ArrayBufferData]] and whose [[ArrayBufferByteLength]] internal slot value is serialized.[[ArrayBufferByteLength]].
Otherwise, if serialized.[[Type]] is "GrowableSharedArrayBuffer", then:
If targetRealm's corresponding agent cluster is not
serialized.[[AgentCluster]], then throw a
"DataCloneError" DOMException.
Otherwise, set value to a new SharedArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is serialized.[[ArrayBufferData]], whose [[ArrayBufferByteLengthData]] internal slot value is serialized.[[ArrayBufferByteLengthData]], and whose [[ArrayBufferMaxByteLength]] internal slot value is serialized.[[ArrayBufferMaxByteLength]].
Otherwise, if serialized.[[Type]] is "ArrayBuffer", then set value to a new ArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is serialized.[[ArrayBufferData]], and whose [[ArrayBufferByteLength]] internal slot value is serialized.[[ArrayBufferByteLength]].
If this throws an exception, catch it, and then throw a
"DataCloneError" DOMException.
Otherwise, if serialized.[[Type]] is "ResizableArrayBuffer", then set value to a new ArrayBuffer object in targetRealm whose [[ArrayBufferData]] internal slot value is serialized.[[ArrayBufferData]], whose [[ArrayBufferByteLength]] internal slot value is serialized.[[ArrayBufferByteLength]], and whose [[ArrayBufferMaxByteLength]] internal slot value is serialized.[[ArrayBufferMaxByteLength]].
If this throws an exception, catch it, and then throw a
"DataCloneError" DOMException.
Otherwise, if serialized.[[Type]] is "ArrayBufferView", then:
Let deserializedArrayBuffer be ? StructuredDeserialize(serialized.[[ArrayBufferSerialized]], targetRealm, memory).
If serialized.[[Constructor]] is "DataView", then set value to a new DataView object in targetRealm whose [[ViewedArrayBuffer]] internal slot value is deserializedArrayBuffer, whose [[ByteLength]] internal slot value is serialized.[[ByteLength]], and whose [[ByteOffset]] internal slot value is serialized.[[ByteOffset]].
Otherwise, set value to a new typed array object in targetRealm, using the constructor given by serialized.[[Constructor]], whose [[ViewedArrayBuffer]] internal slot value is deserializedArrayBuffer, whose [[TypedArrayName]] internal slot value is serialized.[[Constructor]], whose [[ByteLength]] internal slot value is serialized.[[ByteLength]], whose [[ByteOffset]] internal slot value is serialized.[[ByteOffset]], and whose [[ArrayLength]] internal slot value is serialized.[[ArrayLength]].
Otherwise, if serialized.[[Type]] is "Map", then:
Set value to a new Map object in targetRealm whose [[MapData]] internal slot value is a new empty List.
Set deep to true.
Otherwise, if serialized.[[Type]] is "Set", then:
Set value to a new Set object in targetRealm whose [[SetData]] internal slot value is a new empty List.
Set deep to true.
Otherwise, if serialized.[[Type]] is "Array", then:
Let outputProto be targetRealm.[[Intrinsics]].[[%Array.prototype%]].
Set value to ! ArrayCreate(serialized.[[Length]], outputProto).
Set deep to true.
Otherwise, if serialized.[[Type]] is "Object", then:
Set value to a new Object in targetRealm.
Set deep to true.
Otherwise, if serialized.[[Type]] is "Error", then:
Let prototype be %Error.prototype%.
If serialized.[[Name]] is "EvalError", then set prototype to %EvalError.prototype%.
If serialized.[[Name]] is "RangeError", then set prototype to %RangeError.prototype%.
If serialized.[[Name]] is "ReferenceError", then set prototype to %ReferenceError.prototype%.
If serialized.[[Name]] is "SyntaxError", then set prototype to %SyntaxError.prototype%.
If serialized.[[Name]] is "TypeError", then set prototype to %TypeError.prototype%.
If serialized.[[Name]] is "URIError", then set prototype to %URIError.prototype%.
Let message be serialized.[[Message]].
Set value to OrdinaryObjectCreate(prototype, « [[ErrorData]] »).
Let messageDesc be PropertyDescriptor{ [[Value]]: message, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }.
If message is not undefined, then perform !
OrdinaryDefineOwnProperty(value, "message",
messageDesc).
Any interesting accompanying data attached to serialized should be deserialized and attached to value.
Otherwise:
Let interfaceName be serialized.[[Type]].
If the interface identified by interfaceName is not
exposed in targetRealm, then throw a
"DataCloneError" DOMException.
Set value to a new instance of the interface identified by interfaceName, created in targetRealm.
Set deep to true.
Set memory[serialized] to value.
If deep is true, then:
If serialized.[[Type]] is "Map", then:
For each Record { [[Key]], [[Value]] } entry of serialized.[[MapData]]:
Let deserializedKey be ? StructuredDeserialize(entry.[[Key]], targetRealm, memory).
Let deserializedValue be ? StructuredDeserialize(entry.[[Value]], targetRealm, memory).
Append { [[Key]]: deserializedKey, [[Value]]: deserializedValue } to value.[[MapData]].
Otherwise, if serialized.[[Type]] is "Set", then:
For each entry of serialized.[[SetData]]:
Let deserializedEntry be ? StructuredDeserialize(entry, targetRealm, memory).
Append deserializedEntry to value.[[SetData]].
Otherwise, if serialized.[[Type]] is "Array" or "Object", then:
For each Record { [[Key]], [[Value]] } entry of serialized.[[Properties]]:
Let deserializedValue be ? StructuredDeserialize(entry.[[Value]], targetRealm, memory).
Let result be ! CreateDataProperty(value, entry.[[Key]], deserializedValue).
Assert: result is true.
Otherwise:
Perform the appropriate deserialization steps for the interface identified by serialized.[[Type]], given serialized, value, and targetRealm.
Return value.
Other specifications may use the abstract operations defined here. The following provides some guidance on when each abstract operation is typically useful, with examples.
Cloning a value to another realm, with a transfer list, but where the target realm is not known ahead of time. In this case the serialization step can be performed immediately, with the deserialization step delayed until the target realm becomes known.
Creating a realm-independent snapshot of a given value which can be saved for an indefinite amount of time, and then reified back into a JavaScript value later, possibly multiple times.
StructuredSerializeForStorage can be used for situations where the serialization
is anticipated to be stored in a persistent manner, instead of passed between realms. It throws
when attempting to serialize SharedArrayBuffer objects, since storing shared memory
does not make sense. Similarly, it can throw or possibly have different behavior when given a
platform object with custom serialization steps when the
forStorage argument is true.
In general, call sites may pass in Web IDL values instead of JavaScript values; this is to be understood to perform an implicit conversion to the JavaScript value before invoking these algorithms.
Call sites that are not invoked as a result of author code synchronously calling into a user agent method must take care to properly prepare to run script and prepare to run a callback before invoking StructuredSerialize, StructuredSerializeForStorage, or StructuredSerializeWithTransfer abstract operations, if they are being performed on arbitrary objects. This is necessary because the serialization process can invoke author-defined accessors as part of its final deep-serialization steps, and these accessors could call into operations that rely on the entry and incumbent concepts being properly set up.
Support in all current engines.
Every XML and HTML document in an HTML UA is represented by a Document object.
[DOM]
When a Document is created by a script using
the createDocument() or createHTMLDocument() methods, the
Document is ready for post-load tasks immediately.
The document's referrer is a string (representing a URL) that
can be set when the Document is created. If it is not explicitly set, then its value
is the empty string.
Document objectSupport in all current engines.
DOM defines a Document interface, which
this specification extends significantly.
Each Document has an open dialogs list, which is a list of
dialog elements, initially empty.
DocumentOrShadowRoot interfaceDOM defines the DocumentOrShadowRoot mixin, which this specification
extends.
The referrer
attribute must return the document's referrer.
Support in all current engines.
On getting, if the document is a cookie-averse
Document object, then the
user agent must return the empty string. Otherwise, if the Document's origin is an opaque
origin, the user agent must throw a "SecurityError"
DOMException. Otherwise, the user agent must return the cookie-string
for the document's URL for a "non-HTTP" API, decoded
using UTF-8 decode without BOM. [COOKIES]
On setting, if the document is a cookie-averse Document object, then
the user agent must do nothing. Otherwise, if the Document's origin is an opaque
origin, the user agent must throw a "SecurityError"
DOMException. Otherwise, the user agent must act as it would when receiving a set-cookie-string for the document's
URL via a "non-HTTP" API, consisting of the new value
encoded as UTF-8. [COOKIES] [ENCODING]
All the numeric components above, other than the year, must be given as two ASCII digits representing the number in base ten, zero-padded if necessary. The year must be given as the shortest possible string of four or more ASCII digits representing the number in base ten, zero-padded if necessary.
The Document's source file's last modification date and time must be derived from
relevant features of the networking protocols used, e.g. from the value of the HTTP `Last-Modified` header of the document, or from metadata in the
file system for local files. If the last modification date and time are not known, the attribute
must return the current date and time in the above format.
Support in all current engines.
A Document is said to have an active parser if it is associated with an
HTML parser or an XML parser that has not yet been stopped or aborted.
Whenever a render-blocking element el becomes browsing-context disconnected, or el's blocking attribute's value is changed so that el is no longer potentially render-blocking, then unblock rendering on el.
The html element of a document is its document element,
if it's an html element, and null otherwise.
The head attribute,
on getting, must return the head element of the document (a
head element or null).
The title element of a document is the first title element
in the document (in tree order), if there is one, or null otherwise.
Support in all current engines.
On setting, the steps corresponding to the first matching condition in the following list must be run:
svg elementIf there is an SVG title element that is a child of the
document element, let element be the first such element.
Otherwise:
Let element be the result of creating an
element given the document element's node document, "title", and the SVG namespace.
Insert element as the first child of the document element.
String replace all with the given value within element.
If the title element is null and the head
element is null, then return.
If the title element is non-null, let element be
the title element.
Otherwise:
Let element be the result of creating an
element given the document element's node document, "title", and the HTML namespace.
Append element to the
head element.
String replace all with the given value within element.
Do nothing.
The scripts
attribute must return an HTMLCollection rooted at the Document node,
whose filter matches only script elements.
The getElementsByName(elementName) method
steps are to return a live NodeList containing all the HTML
elements in that document that have a name attribute whose value is
identical to the elementName argument, in tree order. When the
method is invoked on a Document object again with the same argument, the user agent
may return the same as the object returned by the earlier call. In other cases, a new
NodeList object must be returned.
The currentScript attribute, on getting, must return
the value to which it was most recently set. When the Document is created, the currentScript must be initialized to null.
The Document interface supports named properties. The supported property names of a
Document object document at any moment consist of the following, in
tree order according to the element that contributed them, ignoring later duplicates,
and with values from id attributes coming before values from name attributes when the same element contributes both:
the value of the name content attribute for all
exposed embed, form, iframe,
img, and exposed object elements that have a non-empty
name content attribute and are in a document tree with
document as their root;
the value of the id content attribute for all
exposed object elements that have a non-empty
id content attribute and are in a document tree with
document as their root; and
the value of the id content attribute for all
img elements that have both a non-empty id content
attribute and a non-empty name content attribute, and are in a
document tree with document as their root.
To determine the value of a named property
name for a Document, the user agent must return the value obtained using
the following steps:
Let elements be the list of named
elements with the name name that are in a document tree with the
Document as their root.
If elements has only one element, and that element is an iframe
element, and that iframe element's content navigable is not null, then
return the active WindowProxy of the element's
content navigable.
Otherwise, if elements has only one element, return that element.
Otherwise, return an HTMLCollection rooted at the Document node,
whose filter matches only named elements with
the name name.
An embed or object element is said to be exposed if it has
no exposed object ancestor, and, for object elements, is
additionally either not showing its fallback content or has no object or
embed descendants.
Elements, attributes, and attribute values in HTML are defined (by this specification) to have
certain meanings (semantics). For example, the ol element represents an ordered list,
and the lang attribute represents the language of the content.
These definitions allow HTML processors, such as web browsers or search engines, to present and use documents and applications in a wide variety of contexts that the author might not have considered.
Authors must not use elements, attributes, or attribute values for purposes other than their appropriate intended semantic purpose, as doing so prevents software from correctly processing the page.
Authors must not use elements, attributes, or attribute values that are not permitted by this specification or other applicable specifications, as doing so makes it significantly harder for the language to be extended in the future.
DOM nodes whose node document's browsing context is null are exempt from all document conformance requirements other than the HTML syntax requirements and XML syntax requirements.
Through scripting and using other mechanisms, the values of attributes, text, and indeed the entire structure of the document may change dynamically while a user agent is processing it. The semantics of a document at an instant in time are those represented by the state of the document at that instant in time, and the semantics of a document can therefore change over time. User agents must update their presentation of the document as this occurs.
The nodes representing HTML elements in the DOM must implement, and expose to scripts, the interfaces listed for them in the relevant sections of this specification. This includes HTML elements in XML documents, even when those documents are in another context (e.g. inside an XSLT transform).
The basic interface, from which all the HTML elements' interfaces inherit, and which must be used by elements that have no additional requirements, is
the HTMLElement interface.
Support in all current engines.
Support in all current engines.
The HTMLElement interface holds methods and attributes related to a number of
disparate features, and the members of this interface are therefore described in various different
sections of this specification.
The element interface for an element with name name in the HTML namespace is determined as follows:
If name is applet, bgsound, blink,
isindex, keygen, multicol, nextid, or
spacer, then return HTMLUnknownElement.
If name is acronym, basefont, big,
center, nobr, noembed, noframes,
plaintext, rb, rtc, strike, or
tt, then return HTMLElement.
If name is listing or xmp, then return
HTMLPreElement.
Otherwise, if this specification defines an interface appropriate for the element type corresponding to the local name name, then return that interface.
If other applicable specifications define an appropriate interface for name, then return the interface they define.
If name is a valid custom element name, then return
HTMLElement.
Return HTMLUnknownElement.
Features shared between HTML and SVG elements use the HTMLOrSVGElement interface
mixin: [SVG]
The [HTMLConstructor] extended attribute must take no
arguments, and must only appear on constructor
operations. It must appear only once on a constructor operation, and the interface must
contain only the single, annotated constructor operation, and no others. The annotated
constructor operation must be declared to take no arguments.
Interfaces declared with constructor operations that are annotated with the [HTMLConstructor] extended attribute have the following
overridden constructor steps:
Let registry be current global object's custom element registry.
If NewTarget is equal to the active function
object, then throw a TypeError.
Let definition be the item in registry's custom element
definition set with constructor equal to
NewTarget. If there is no such item, then throw a TypeError.
Let isValue be null.
If definition's local name is equal to definition's name (i.e., definition is for an autonomous custom element):
If the active function object is not HTMLElement, then throw a
TypeError.
Otherwise (i.e., if definition is for a customized built-in element):
Let valid local names be the list of local names for elements defined in this specification or in other applicable specifications that use the active function object as their element interface.
If valid local names does not contain definition's local name, then throw a
TypeError.
Set isValue to definition's name.
If definition's construction stack is empty:
Let element be the result of internally creating a new object implementing the interface to which the active function object corresponds, given the current realm and NewTarget.
Set element's node document to the current global
object's associated
Document.
Set element's namespace to the HTML namespace.
Set element's namespace prefix to null.
Set element's local name to definition's local name.
Set element's custom element state to "custom".
Set element's custom element definition to definition.
Set element's is value to isValue.
Return element.
If prototype is not an Object, then:
Let realm be ? GetFunctionRealm(NewTarget).
Set prototype to the interface prototype object of realm whose interface is the same as the interface of the active function object.
Let element be the last entry in definition's construction stack.
If element is an already
constructed marker, then throw a TypeError.
Perform ? element.[[SetPrototypeOf]](prototype).
Replace the last entry in definition's construction stack with an already constructed marker.
Return element.
In addition to the constructor behavior implied by [HTMLConstructor], some elements also have named constructors (which are really factory functions with a modified prototype property).
Each element in this specification has a definition that includes the following information:
A list of categories to which the element belongs. These are used when defining the content models for each element.
A non-normative description of where the element can be used. This information is redundant with the content models of elements that allow this one as a child, and is provided only as a convenience.
A normative description of what content must be included as children and descendants of the element.
A non-normative description of whether, in the text/html syntax, the
start and end tags can
be omitted. This information is redundant with the normative requirements given in the optional tags section, and is provided in the element
definitions only as a convenience.
A normative list of attributes that may be specified on the element (except where otherwise disallowed), along with non-normative descriptions of those attributes. (The content to the left of the dash is normative, the content to the right of the dash is not.)
For authors: Conformance requirements for use of ARIA role and aria-* attributes are
defined in ARIA in HTML. [ARIA] [ARIAHTML]
For implementers: User agent requirements for implementing accessibility API semantics are defined in HTML Accessibility API Mappings. [HTMLAAM]
A normative definition of a DOM interface that such elements must implement.
This is then followed by a description of what the element represents, along with any additional normative conformance criteria that may apply to authors and implementations. Examples are sometimes also included.
An attribute value is a string. Except where otherwise specified, attribute values on HTML elements may be any string value, including the empty string, and there is no restriction on what text can be specified in such attribute values.
Inter-element whitespace, comment nodes, and processing instruction nodes must be ignored when establishing whether an element's contents match the element's content model or not, and must be ignored when following algorithms that define document and element semantics.
Authors must not use HTML elements anywhere except where they are explicitly allowed, as defined for each element, or as explicitly required by other specifications. For XML compound documents, these contexts could be inside elements from other namespaces, if those elements are defined as providing the relevant contexts.
In addition, HTML elements may be orphan nodes (i.e. without a parent node).
When an element's content model is nothing, the
element must contain no Text nodes (other than inter-element whitespace)
and no element nodes.
These categories are related as follows:
Sectioning content, heading content, phrasing content, embedded content, and interactive content are all types of flow content. Metadata is sometimes flow content. Metadata and interactive content are sometimes phrasing content. Embedded content is also a type of phrasing content, and sometimes is interactive content.
Other categories are also used for specific purposes, e.g. form controls are specified using a number of categories to define common requirements. Some elements have unique requirements and do not fit into any particular category.
Elements from other namespaces whose semantics are primarily metadata-related (e.g. RDF) are also metadata content.
Text nodes and attribute values must consist of scalar
values, excluding noncharacters, and controls other than ASCII whitespace.
This specification includes extra constraints on the exact value of Text nodes and
attribute values depending on their precise context.
Elements that are from namespaces other than the HTML namespace and that convey content but not metadata, are embedded content for the purposes of the content models defined in this specification. (For example, MathML or SVG.)
Some embedded content elements can have fallback content: content that is to be used when the external resource cannot be used (e.g. because it is of an unsupported format). The element definitions state what the fallback is, if any.
This requirement is not a hard requirement, however, as there are many cases where an element can be empty legitimately, for example when it is used as a placeholder which will later be filled in by a script, or when the element is part of a template and would on most pages be filled in but on some pages is not relevant.
Conformance checkers are encouraged to provide a mechanism for authors to find elements that fail to fulfill this requirement, as an authoring aid.
The following elements are palpable content:
aabbraddressarticleasideaudio (if the controls attribute is present)bbdibdoblockquotebuttoncanvascitecodedatadeldetailsdfndivdl (if the element's children include at least one name-value group)emembedfieldsetfigurefooterformh1h2h3h4h5h6headerhgroupiiframeimginput (if the type attribute is not in the state)inskbdlabelmainmapmarkmathmenu (if the element's children include at least one li element)meternavobjectol (if the element's children include at least one li element)outputppicturepreprogressqrubyssampsearchsectionselectsmallspanstrongsubsupsvgtabletextareatimeuul (if the element's children include at least one li element)varvideoThe following elements are script-supporting elements:
When a transparent element has no parent, then the part of its content model that is "transparent" must instead be treated as accepting any flow content.
Paragraphs in flow content are defined relative to what the document looks like
without the a, ins, del, and map elements
complicating matters, since those elements, with their hybrid content models, can straddle
paragraph boundaries, as shown in the first two examples below.
Let view be a view of the DOM that replaces all a,
ins, del, and map elements in the document with their contents. Then, in view, for each run
of sibling phrasing content nodes uninterrupted by other types of content, in an
element that accepts content other than phrasing content as well as phrasing
content, let first be the first node of the run, and let last be the last node of the run. For each such run that consists of at least one
node that is neither embedded content nor inter-element whitespace, a
paragraph exists in the original DOM from immediately before first to
immediately after last. (Paragraphs can thus span across a,
ins, del, and map elements.)
Conformance checkers may warn authors of cases where they have paragraphs that overlap each
other (this can happen with object, video, audio, and
canvas elements, and indirectly through elements in other namespaces that allow HTML
to be further embedded therein, like SVG svg or MathML
math).
A paragraph is also formed explicitly by p elements.
The following attributes are common to and may be specified on all HTML elements (even those not defined in this specification):
accesskeyautocapitalizeautocorrectautofocuscontenteditabledirdraggableenterkeyhintinertinputmodeisitemiditempropitemrefitemscopeitemtypelangnoncepopoverspellcheckstyletabindextitletranslatewritingsuggestionsThese attributes are only defined by this specification as attributes for HTML elements. When this specification refers to elements having these attributes, elements from namespaces that are not defined as having these attributes must not be considered as being elements with these attributes.
Support in all current engines.
The class, id, and slot attributes may be specified on all HTML elements.
When specified on HTML elements, the class
attribute must have a value that is a set of space-separated tokens representing the
various classes that the element belongs to.
When specified on HTML elements, the id attribute
value must be unique amongst all the IDs in the element's
tree and must contain at least one character. The value must not contain any
ASCII whitespace.
Identifiers are opaque strings. Particular meanings should not be derived from the value of the
id attribute.
There are no conformance requirements for the slot attribute
specific to HTML elements.
To enable assistive technology products to expose a more fine-grained interface than is
otherwise possible with HTML elements and attributes, a set of annotations
for assistive technology products can be specified (the ARIA role and aria-* attributes).
[ARIA]
The following event handler content attributes may be specified on any HTML element:
onauxclickonbeforeinputonbeforematchonbeforetoggleonblur*oncanceloncanplayoncanplaythroughonchangeonclickoncloseoncontextlostoncontextmenuoncontextrestoredoncopyoncuechangeoncutondblclickondragondragendondragenterondragleaveondragoverondragstartondropondurationchangeonemptiedonendedonerror*onfocus*onformdataoninputoninvalidonkeydownonkeypressonkeyuponload*onloadeddataonloadedmetadataonloadstartonmousedownonmouseenteronmouseleaveonmousemoveonmouseoutonmouseoveronmouseuponpasteonpauseonplayonplayingonprogressonratechangeonresetonresize*onscroll*onscrollend*onsecuritypolicyviolationonseekedonseekingonselectonslotchangeonstalledonsubmitonsuspendontimeupdateontoggleonvolumechangeonwaitingonwheelCustom data attributes (e.g. data-foldername or data-msgid) can be specified on any
HTML element, to store custom data, state, annotations, and
similar, specific to the page.
In HTML documents, elements in the HTML namespace may have an xmlns attribute specified, if, and only if, it has the exact value "http://www.w3.org/1999/xhtml". This does not apply to XML
documents.
XML also allows the use of the xml:space
attribute in the XML namespace on any element in an XML
document. This attribute has no effect on HTML elements, as the default
behavior in HTML is to preserve whitespace. [XML]
title attributeSupport in all current engines.
If this attribute is omitted from an element, then it implies that the title attribute of the nearest ancestor HTML element with a title attribute set is also
relevant to this element. Setting the attribute overrides this, explicitly stating that the
advisory information of any ancestors is not relevant to this element. Setting the attribute to
the empty string indicates that the element has no advisory information.
If the title attribute's value contains U+000A LINE FEED (LF)
characters, the content is split into multiple lines. Each U+000A LINE FEED (LF) character
represents a line break.
Some elements, such as link, abbr, and input, define
additional semantics for the title attribute beyond the semantics
described above.
User agents should inform the user when elements have advisory information, otherwise the information would not be discoverable.
Support in all current engines.
The title IDL attribute
must reflect the title content attribute.
lang and xml:lang
attributesSupport in all current engines.
If these attributes are omitted from an element, then the language of this element is the same
as the language of its parent element, if any (except for slot elements in a
shadow tree).
The lang attribute in no namespace may be used on any HTML element.
The lang attribute in the XML
namespace may be used on HTML elements in XML documents,
as well as elements in other namespaces if the relevant specifications allow it (in particular,
MathML and SVG allow lang attributes in the
XML namespace to be specified on their elements). If both the lang attribute in no namespace and the lang attribute in the XML namespace are specified on the same
element, they must have exactly the same value when compared in an ASCII
case-insensitive manner.
Authors must not use the lang attribute in
the XML namespace on HTML elements in HTML
documents. To ease migration to and from XML, authors may specify an attribute in no
namespace with no prefix and with the literal localname "xml:lang" on
HTML elements in HTML documents, but such attributes must only be
specified if a lang attribute in no namespace is also specified,
and both attributes must have the same value when compared in an ASCII
case-insensitive manner.
If the resulting value is not a recognized language tag, then it must be treated as an unknown language having the given language tag, distinct from all other languages. For the purposes of round-tripping or communicating with other services that expect language tags, user agents should pass unknown language tags through unmodified, and tagged as being BCP 47 language tags, so that subsequent services do not interpret the data as another type of language description. [BCP47]
If the resulting value is the empty string, then it must be interpreted as meaning that the language of the node is explicitly unknown.
User agents may use the element's language to determine proper processing or rendering (e.g. in the selection of appropriate fonts or pronunciations, for dictionary selection, or for the user interfaces of form controls such as date pickers).
Support in all current engines.
The lang IDL attribute
must reflect the lang content attribute in no
namespace.
translate attributeSupport in all current engines.
The translate
attribute is used to specify whether an element's attribute values and the values of its
Text node children are to be translated when the page is localized, or whether to
leave them unchanged. It is an attribute is an enumerated attribute with the
following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
yes
| yes | Sets translation mode to translate-enabled. |
| (the empty string) | ||
no
| no | Sets translation mode to no-translate. |
Other specifications may define other attributes that are also translatable
attributes. For example, ARIA would define the aria-label attribute as translatable.
The translate IDL
attribute must, on getting, return true if the element's translation mode is
translate-enabled, and false otherwise. On setting, it must set the content
attribute's value to "yes" if the new value is true, and set the content
attribute's value to "no" otherwise.
dir attributeSupport in all current engines.
The dir attribute
is an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
ltr
| ltr | The contents of the element are explicitly directionally isolated left-to-right text. |
rtl
| rtl | The contents of the element are explicitly directionally isolated right-to-left text. |
auto
| auto | The contents of the element are explicitly directionally isolated text, but the direction is to be determined programmatically using the contents of the element (as described below). |
The attribute's missing value default and invalid value default are both the undefined state.
To compute the contained text auto directionality of an element element with a boolean canExcludeRoot:
For each node descendant of element's descendants, in tree order:
If any of
is one of
bdi elementscript elementstyle elementtextarea elementdir attribute is not in the undefined statethen continue.
If descendant is a slot element whose root is a
shadow root, then return the directionality of that shadow root's host.
Let result be the text node directionality of descendant.
If result is not null, then return result.
Return null.
Support in all current engines.
The dir IDL attribute on
an element must reflect the dir content attribute of
that element, limited to only known values.
Support in all current engines.
The dir IDL
attribute on Document objects must reflect the dir content attribute of the html element, if
any, limited to only known values. If there is no such element, then the attribute
must return the empty string and do nothing on setting.
style attributeSupport in all current engines.
In user agents that support CSS, the attribute's value must be parsed when the attribute is added or has its value changed, according to the rules given for style attributes. [CSSATTR]
However, if the Should element's inline behavior be blocked by Content Security
Policy? algorithm returns "Blocked" when executed upon the
attribute's element, "style attribute", and the attribute's
value, then the style rules defined in the attribute's value must not be applied to the
element. [CSP]
Documents that use style attributes on any of their elements
must still be comprehensible and usable if those attributes were removed.
The style IDL attribute is defined in CSS Object
Model. [CSSOM]
data-* attributesSupport in all current engines.
A custom data attribute is an attribute in no namespace whose name starts with the
string "data-", has at least one character after the
hyphen, is XML-compatible, and contains no ASCII
upper alphas.
Custom data attributes are intended to store custom data, state, annotations, and similar, private to the page or application, for which there are no more appropriate attributes or elements.
These attributes are not intended for use by software that is not known to the administrators of the site that uses the attributes. For generic extensions that are to be used by multiple independent tools, either this specification should be extended to provide the feature explicitly, or a technology like microdata should be used (with a standardized vocabulary).
Every HTML element may have any number of custom data attributes specified, with any value.
Authors should carefully design such extensions so that when the attributes are ignored and any associated CSS dropped, the page is still usable.
User agents must not derive any implementation behavior from these attributes or values. Specifications intended for user agents must not define these attributes to have any meaningful values.
JavaScript libraries may use the custom data attributes, as they are considered to be part of the page on which they are used. Authors of libraries that are reused by many authors are encouraged to include their name in the attribute names, to reduce the risk of clashes. Where it makes sense, library authors are also encouraged to make the exact name used in the attribute names customizable, so that libraries whose authors unknowingly picked the same name can be used on the same page, and so that multiple versions of a particular library can be used on the same page even when those versions are not mutually compatible.
The DOMStringMap interface is used for the dataset attribute. Each DOMStringMap has an associated element.
The supported property names on a DOMStringMap object at any instant
are the names of each pair returned from getting the
DOMStringMap's name-value pairs at that instant, in the order returned.
To determine the value of a named property
name for a DOMStringMap, return the value component of the name-value pair
whose name component is name in the list returned from getting the DOMStringMap's name-value
pairs.
To set the value of a new named property or
set the value of an existing named property for a DOMStringMap, given a
property name name and a new value value, run the following steps:
If name contains a U+002D HYPHEN-MINUS character (-) followed by an ASCII
lower alpha, then throw a "SyntaxError"
DOMException.
For each ASCII upper alpha in name, insert a U+002D HYPHEN-MINUS character (-) before the character and replace the character with the same character converted to ASCII lowercase.
Insert the string data- at the front of name.
If name does not match the XML Name production,
throw an "InvalidCharacterError" DOMException.
Set an attribute value for the
DOMStringMap's associated element
using name and value.
To delete an existing named property
name for a DOMStringMap, run the following steps:
For each ASCII upper alpha in name, insert a U+002D HYPHEN-MINUS character (-) before the character and replace the character with the same character converted to ASCII lowercase.
Insert the string data- at the front of name.
Remove an attribute by name given
name and the DOMStringMap's associated element.
innerText and outerText propertiesSupport in all current engines.
Support in all current engines.
The innerText setter steps are to run set the inner
text steps.
The outerText setter steps are:
If this's parent is null, then throw a
"NoModificationAllowedError" DOMException.
Let next be this's next sibling.
Let previous be this's previous sibling.
Let fragment be the rendered text fragment for the given value given this's node document.
If fragment has no children, then
append a new Text node whose data is the empty string and node document is
this's node document to fragment.
If next is non-null and next's previous sibling is a
Text node, then merge with the next text node given next's
previous sibling.
If previous is a Text node, then merge with the next text
node given previous.
Text content in HTML elements with Text nodes in their
contents, and text in attributes of HTML
elements that allow free-form text, may contain characters in the ranges U+202A to U+202E
and U+2066 to U+2069 (the bidirectional-algorithm formatting characters). [BIDI]
User agents must implement the Unicode bidirectional algorithm to determine the proper ordering of characters when rendering documents and parts of documents. [BIDI]
The mapping of HTML to the Unicode bidirectional algorithm must be done in one of three ways. Either the user agent must implement CSS, including in particular the CSS 'unicode-bidi', 'direction', and 'content' properties, and must have, in its user agent style sheet, the rules using those properties given in this specification's rendering section, or, alternatively, the user agent must act as if it implemented just the aforementioned properties and had a user agent style sheet that included all the aforementioned rules, but without letting style sheets specified in documents override them, or, alternatively, the user agent must implement another styling language with equivalent semantics. [CSSGC]
The following elements and attributes have requirements defined by the rendering section that, due to the requirements in this section, are requirements on all user agents (not just those that support the suggested default rendering):
User agent requirements for implementing Accessibility API semantics on HTML elements are defined in HTML Accessibility API Mappings. In addition to the rules there, for a custom element element, the default ARIA role semantics are determined as follows: [HTMLAAM]
Let map be element's internal content attribute map.
If map["role"] exists,
then return it.
Return no role.
Similarly, for a custom element element, the default ARIA state and property semantics, for a state or property named stateOrProperty, are determined as follows:
If element's attached internals is non-null:
If element's attached internals's get the stateOrProperty-associated element exists, then return the result of running it.
If element's attached internals's get the stateOrProperty-associated elements exists, then return the result of running it.
If element's internal content attribute map[stateOrProperty] exists, then return it.
Return the default value for stateOrProperty.
For an example of this in action, see the custom elements section.
Conformance checker requirements for checking use of ARIA role and aria-* attributes on
HTML elements are defined in ARIA in HTML. [ARIAHTML]
html elementSupport in all current engines.
Support in all current engines.
head element followed by a body element.html element's start tag can be omitted
if the first thing inside the html element is not a comment.html element's end tag can be omitted if
the html element is not immediately followed by a comment.The html element represents the root of an HTML document.
Authors are encouraged to specify a lang attribute on the root
html element, giving the document's language. This aids speech synthesis tools to
determine what pronunciations to use, translation tools to determine what rules to use, and so
forth.
head elementSupport in all current engines.
Support in all current engines.
html element.iframe srcdoc document or if title information is available from a higher-level protocol: Zero or more elements of metadata content, of which no more than one is a title element and no more than one is a base element.title element and no more than one is a base element.head element's start tag can be omitted if
the element is empty, or if the first thing inside the head element is an
element.head element's end tag can be omitted if
the head element is not immediately followed by ASCII whitespace or a
comment.The head element represents a collection of metadata for the
Document.
title elementSupport in all current engines.
Support in all current engines.
head element containing no other title elements.The title element represents the document's title or name. Authors
should use titles that identify their documents even when they are used out of context, for
example in a user's history or bookmarks, or in search results. The document's title is often
different from its first heading, since the first heading does not have to stand alone when taken
out of context.
There must be no more than one title element per document.
The text attribute's setter must string replace
all with the given value within this title element.
The string to use as the document's title is given by the document.title IDL attribute.
User agents should use the document's title when referring to the document in their user
interface. When the contents of a title element are used in this way, the
directionality of that title element should be used to set the directionality
of the document's title in the user interface.
base elementSupport in all current engines.
Support in all current engines.
head element containing no other base elements.href — Document base URL
target — Default navigable for hyperlink navigation and form submission
The base element allows authors to specify the document base URL for
the purposes of parsing URLs, and the name of the default
navigable for the purposes of following hyperlinks. The element does not
represent any content beyond this information.
There must be no more than one base element per document.
A base element must have either an href
attribute, a target attribute, or both.
A base element, if it has an href attribute,
must come before any other elements in the tree that have attributes defined as taking URLs.
A base element, if it has a target
attribute, must come before any elements in the tree that represent hyperlinks.
The href IDL attribute, on setting, must set the href content attribute to the given new value.
The target IDL
attribute must reflect the content attribute of the same name.
link elementSupport in all current engines.
Support in all current engines.
noscript element that is a child of a head element.href — Address of the hyperlink
crossorigin — How the element handles crossorigin requests
rel — Relationship between the document containing the hyperlink and the destination resource
media — Applicable media
integrity — Integrity metadata used in Subresource Integrity checks [SRI]
hreflang — Language of the linked resource
type — Hint for the type of the referenced resource
referrerpolicy — Referrer policy for fetches initiated by the element
sizes — Sizes of the icons (for rel="icon")
imagesrcset — Images to use in different situations, e.g., high-resolution displays, small monitors, etc. (for rel="preload")
imagesizes — Image sizes for different page layouts (for rel="preload")
as — Potential destination for a preload request (for rel="preload" and rel="modulepreload")
blocking — Whether the element is potentially render-blocking
color — Color to use when customizing a site's icon (for rel="mask-icon")
disabled — Whether the link is disabled
fetchpriority — Sets the priority for fetches initiated by the element
title attribute has special semantics on this element: Title of the link; CSS style sheet set name
The link element allows authors to link their document to other resources.
If both the href and imagesrcset attributes are absent, then the element does not
define a link.
rel's
supported tokens are the keywords defined in
HTML link types which are allowed on link elements, impact
the processing model, and are supported by the user agent. The possible supported tokens are
alternate,
dns-prefetch,
expect,
icon,
manifest,
modulepreload,
next,
pingback,
preconnect,
prefetch,
preload,
search, and
stylesheet.
rel's supported
tokens must only include the tokens from this list that the user agent implements the
processing model for.
A link element must have either a rel
attribute or an itemprop attribute, but not both.
If a link element has an itemprop attribute,
or has a rel attribute that contains only keywords that are
body-ok, then the element is said to be allowed in the body. This means
that the element can be used where phrasing content is expected.
Two categories of links can be created using the link element: links to external resources and hyperlinks. The link types section defines
whether a particular link type is an external resource or a hyperlink. One link
element can create multiple links (of which some might be external resource links and some might be hyperlinks); exactly which and how many links are created depends on the
keywords given in the rel attribute. User agents must process
the links on a per-link basis, not a per-element basis.
Hyperlinks created with the link element and its
rel attribute apply to the whole document. This contrasts with
the rel attribute of a and area
elements, which indicates the type of a link whose context is given by the link's location within
the document.
Unlike those created by a and area elements, hyperlinks created by link elements are not displayed as
part of the document by default, in user agents that support the suggested
default rendering. And even if they are force-displayed using CSS, they have no
activation behavior. Instead, they primarily provide semantic information which might
be used by the page or by other software that consumes the page's contents. Additionally, the user
agent can provide
its own UI for following such hyperlinks.
The exact behavior for links to external resources depends on the exact relationship, as defined for the relevant link type.
The media attribute
says which media the resource applies to. The value must be a valid media query
list.
Support in all current engines.
For external resource links, the type attribute is used as a hint to user agents so that they can
avoid fetching resources they do not support.
The title attribute
gives the title of the link. With one exception, it is purely advisory. The value is text. The
exception is for style sheet links that are in a document tree, for which the title attribute defines CSS
style sheet sets.
The imagesrcset and href attributes (if width
descriptors are not used) together contribute the image
sources to the source set.
The imagesrcset and imagesizes attributes must only be specified on
link elements that have both a rel attribute that
specifies the preload keyword, as well as an as attribute in the "image" state.
The sizes attribute
gives the sizes of icons for visual media. Its value, if present, is merely advisory. User agents may use the value to decide which icon(s) to use if multiple icons are
available. If specified, the attribute must have a value that is an unordered set of
unique space-separated tokens which are ASCII case-insensitive. Each value
must be either an ASCII case-insensitive match for the string "any", or a value that consists of two valid non-negative integers that do not have a leading U+0030 DIGIT
ZERO (0) character and that are separated by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN
CAPITAL LETTER X character. The attribute must only be specified on link elements
that have a rel attribute that specifies the icon keyword or the apple-touch-icon keyword.
The processing model for how the as attribute is
used is given in an individual link type's fetch and process the linked resource
algorithm.
The blocking
attribute is a blocking attribute. It is used by link types stylesheet and expect, and it must only be specified on link elements
that have a rel attribute containing those keywords.
The color attribute is
used with the mask-icon link type. The attribute must only be specified on
link elements that have a rel attribute that
contains the mask-icon keyword. The value must be a string that matches the
CSS <color> production, defining a suggested color that user agents can use to
customize the display of the icon that the user sees when they pin your site.
Whenever the disabled attribute is removed, set the
link element's explicitly enabled attribute to true.
The fetchpriority attribute is a fetch
priority attribute that is intended for use with external resource links, where it is used to set the priority used when fetching and processing the linked
resource.
Support in all current engines.
The IDL attributes
href,
hreflang,
integrity,
media,
rel,
sizes,
type,
blocking, and
disabled
each must reflect the respective content attributes of the same name.
Support in all current engines.
The crossOrigin IDL attribute must reflect the
crossorigin content attribute, limited to only
known values.
HTMLLinkElement/referrerPolicy
Support in all current engines.
The imageSizes IDL attribute must reflect the
imagesizes content attribute.
Support in all current engines.
The relList
IDL attribute must reflect the rel content attribute.
media attributeIf the link is a hyperlink then the media
attribute is purely advisory, and describes for which media the document in question was
designed.
However, if the link is an external resource link, then the media attribute is prescriptive. The user agent must apply the
external resource when the media attribute's value
matches the environment and the other relevant conditions apply, and must not apply
it otherwise.
The default, if the media attribute is
omitted, is "all", meaning that by default links apply to all media.
type attributeIf the type attribute is present, then the user agent must
assume that the resource is of the given type (even if that is not a valid MIME type
string, e.g. the empty string). If the attribute is omitted, but the external
resource link type has a default type defined, then the user agent must assume that the
resource is of that type. If the UA does not support the given MIME type for the
given link relationship, then the UA should not fetch and process the linked
resource; if the UA does support the given MIME type for the given link
relationship, then the UA should fetch and process the linked resource at the
appropriate time as specified for the external resource link's particular type.
If the attribute is omitted, and the external resource link type does not have a
default type defined, but the user agent would fetch and process the linked resource
if the type was known and supported, then the user agent should fetch and process the linked
resource under the assumption that it will be supported.
User agents must not consider the type attribute
authoritative — upon fetching the resource, user agents must not use the type attribute to determine its actual type. Only the actual type
(as defined in the next paragraph) is used to determine whether to apply the resource,
not the aforementioned assumed type.
If the external resource link type defines rules for processing the resource's Content-Type metadata, then those rules apply. Otherwise, if the resource is expected to be an image, user agents may apply the image sniffing rules, with the official type being the type determined from the resource's Content-Type metadata, and use the resulting computed type of the resource as if it was the actual type. Otherwise, if neither of these conditions apply or if the user agent opts not to apply the image sniffing rules, then the user agent must use the resource's Content-Type metadata to determine the type of the resource. If there is no type metadata, but the external resource link type has a default type defined, then the user agent must assume that the resource is of that type.
Once the user agent has established the type of the resource, the user agent must apply the resource if it is of a supported type and the other relevant conditions apply, and must ignore the resource otherwise.
link elementAll external resource
links have a fetch and process the linked resource algorithm, which takes a
link element el. They also have linked resource fetch setup
steps which take a link element el and request request. Individual link types may provide
their own fetch and process the linked resource algorithm, but unless explicitly
stated, they use the default fetch and process the linked resource algorithm.
Similarly, individual link types may provide their own linked resource fetch setup
steps, but unless explicitly stated, these steps just return true.
User agents may opt to only try to fetch and process such resources when they are needed, instead of pro-actively fetching all the external resources that are not applied.
Unless otherwise specified for a given rel keyword, the
element must delay the load event of the element's node document until
all the attempts to fetch and process the linked resource and its critical
subresources are complete. (Resources that the user agent has not yet attempted to fetch
and process, e.g., because it is waiting for the resource to be needed, do not delay the
load event.)
Link` headersIn addition to the `Link` headers, it is possible that the 103
response contains a Content Security Policy header, which is enforced when processing
the early hint.
link
elementInteractive user agents may provide users with a means to follow the hyperlinks created using the link element, somewhere
within their user interface. Such invocations of the follow
the hyperlink algorithm must set the userInvolvement argument to "browser UI". The exact interface is not defined by this
specification, but it could include the following information (obtained from the element's
attributes, again as defined below), in some form or another (possibly simplified), for each
hyperlink created with each link element in the document:
rel attribute)title
attribute).href
attribute).hreflang
attribute).media
attribute).User agents could also include other information, such as the type of the resource (as given by
the type attribute).
meta
elementSupport in all current engines.
Support in all current engines.
itemprop attribute is present: flow content.itemprop attribute is present: phrasing content.charset attribute is present, or if the element's http-equiv attribute is in the Encoding declaration state: in a head element.http-equiv attribute is present but not in the Encoding declaration state: in a head element.http-equiv attribute is present but not in the Encoding declaration state: in a noscript element that is a child of a head element.name attribute is present: where metadata content is expected.itemprop attribute is present: where metadata content is expected.itemprop attribute is present: where phrasing content is expected.name — Metadata name
http-equiv — Pragma directive
content — Value of the element
charset — Character encoding declaration
media — Applicable media
The meta element represents various kinds of metadata that cannot be
expressed using the title, base, link, style,
and script elements.
The meta element can represent document-level metadata with the name attribute, pragma directives with the http-equiv attribute, and the file's character encoding
declaration when an HTML document is serialized to string form (e.g. for transmission over
the network or for disk storage) with the charset
attribute.
Exactly one of the name, http-equiv, charset,
and itemprop attributes must be specified.
If either name, http-equiv, or itemprop is
specified, then the content attribute must also be
specified. Otherwise, it must be omitted.
There must not be more than one meta element with a charset attribute per document.
The name, content, and media IDL attributes
must reflect the respective content attributes of the same name. The IDL attribute
httpEquiv must
reflect the content attribute http-equiv.
Support in all current engines.
This specification defines a few names for the name
attribute of the meta element.
Names are case-insensitive, and must be compared in an ASCII case-insensitive manner.
application-nameThe value must be a short free-form string giving the name of the web application that the
page represents. If the page is not a web application, the application-name metadata name must not be used.
Translations of the web application's name may be given, using the lang attribute to specify the language of each name.
There must not be more than one meta element with a given language
and where the name attribute value is an
ASCII case-insensitive match for
application-name per document.
User agents may use the application name in UI in preference to the page's
title, since the title might include status messages and the like relevant to the
status of the page at a particular moment in time instead of just being the name of the
application.
To find the application name to use given an ordered list of languages (e.g. British English, American English, and English), user agents must run the following steps:
Let languages be the list of languages.
Let default language be the language of the
Document's document element, if any, and if that language is not
unknown.
If there is a default language, and if it is not the same language as any of the languages in languages, append it to languages.
Let winning language be the first language in languages for which
there is a meta element in the Document where the
name attribute value is an
ASCII case-insensitive match for
application-name and whose
language is the language in question.
If none of the languages have such a meta element, then return;
there's no given application name.
Return the value of the content attribute of the
first meta element in the Document in tree order where the
name attribute value is an
ASCII case-insensitive match for application-name
and whose language is winning language.
authorThe value must be a free-form string giving the name of one of the page's authors.
descriptionThe value must be a free-form string that describes the page. The value must be
appropriate for use in a directory of pages, e.g. in a search engine. There must not be more than
one meta element where the name attribute value
is an ASCII case-insensitive match for
description per document.
generatorThe value must be a free-form string that identifies one of the software packages used to generate the document. This value must not be used on pages whose markup is not generated by software, e.g. pages whose markup was written by a user in a text editor.
keywordsThe value must be a set of comma-separated tokens, each of which is a keyword relevant to the page.
To obtain the list of keywords that the author has specified as applicable to the page, the user agent must run the following steps:
Let keywords be an empty list.
For each meta element with a name
attribute and a content attribute and where the name attribute value is an ASCII case-insensitive
match for keywords:
Split the value of the element's content attribute on commas.
Add the resulting tokens, if any, to keywords.
Remove any duplicates from keywords.
Return keywords. This is the list of keywords that the author has specified as applicable to the page.
User agents should not use this information when there is insufficient confidence in the reliability of the value.
referrerThe value must be a referrer policy, which defines the default referrer
policy for the Document. [REFERRERPOLICY]
If any meta element element is inserted into the document, or has its name or content
attributes changed, user agents must run the following algorithm:
If element is not in a document tree, then return.
If element does not have a name
attribute whose value is an ASCII case-insensitive match for "referrer", then return.
If element does not have a content
attribute, or that attribute's value is the empty string, then return.
Let value be the value of element's content attribute, converted to ASCII
lowercase.
If value is one of the values given in the first column of the following table, then set value to the value given in the second column:
| Legacy value | Referrer policy |
|---|---|
never
| no-referrer
|
default
| the default referrer policy |
always
| unsafe-url
|
origin-when-crossorigin
| origin-when-cross-origin
|
If value is a referrer policy, then set element's node document's policy container's referrer policy to policy.
theme-colorThe value must be a string that matches the CSS <color> production, defining a suggested color that user agents should use to customize the display of the page or of the surrounding user interface. For example, a browser might color the page's title bar with the specified value, or use it as a color highlight in a tab bar or task switcher.
Within an HTML document, the media attribute value must
be unique amongst all the meta elements with their name attribute value set to an ASCII
case-insensitive match for theme-color.
The media attribute may be used to describe the context
in which the provided color should be used.
To obtain a page's theme color, user agents must run the following steps:
Let candidate elements be the list of all meta elements that
meet the following criteria, in tree order:
the element is in a document tree;
the element has a name attribute, whose value
is an ASCII case-insensitive match for theme-color; and
the element has a content attribute.
For each element in candidate elements:
If element has a media attribute
and the value of element's media
attribute does not match the environment, then
continue.
Let value be the result of stripping leading and trailing ASCII whitespace from the value of
element's content attribute.
Let color be the result of parsing value.
If color is not failure, then return color.
Return nothing (the page has no theme color).
If any meta elements are inserted into the document or removed from the document, or existing meta elements have their
name, content, or
media attributes changed, or if the environment changes
such that any meta element's media
attribute's value may now or may no longer match the
environment, user agents must re-run the above algorithm and apply the result to any
affected UI.
When using the theme color in UI, user agents may adjust it in implementation-specific ways to make it more suitable for the UI in question. For example, if a user agent intends to use the theme color as a background and display white text over it, it might use a darker variant of the theme color in that part of the UI, to ensure adequate contrast.
color-schemeTo aid user agents in rendering the page background with the desired color scheme immediately
(rather than waiting for all CSS in the page to load), a 'color-scheme' value can
be provided in a meta element.
The value must be a string that matches the syntax for the CSS 'color-scheme' property value. It determines the page's supported color-schemes.
There must not be more than one meta element with its name attribute value set to an
ASCII case-insensitive match for color-scheme per document.
To obtain a page's supported color-schemes, user agents must run the following steps:
Let candidate elements be the list of all meta elements that
meet the following criteria, in tree order:
the element is in a document tree;
the element has a name attribute, whose value
is an ASCII case-insensitive match for color-scheme; and
the element has a content attribute.
For each element in candidate elements:
content attribute.Return null.
If any meta elements are inserted into the document or removed from the document, or existing meta elements have their
name or content
attributes changed, user agents must re-run the above algorithm.
However, a new metadata name should not be created in any of the following cases:
If either the name is a URL, or the value of its accompanying content attribute is a URL; in those cases,
registering it as an extension to the predefined set of
link types is encouraged (rather than creating a new metadata name).
If the name is for something expected to have processing requirements in user agents; in that case it ought to be standardized.
Also, before creating and using a new metadata name, consulting the WHATWG Wiki MetaExtensions page is encouraged — to avoid choosing a metadata name that's already in use, and to avoid duplicating the purpose of any metadata names that are already in use, and to avoid new standardized names clashing with your chosen name. [WHATWGWIKI]
Anyone is free to edit the WHATWG Wiki MetaExtensions page at any time to add a metadata name. New metadata names can be specified with the following information:
The actual name being defined. The name should not be confusingly similar to any other defined name (e.g. differing only in case).
A short non-normative description of what the metadata name's meaning is, including the format the value is required to be in.
A list of other names that have exactly the same processing requirements. Authors should not use the names defined to be synonyms (they are only intended to allow user agents to support legacy content). Anyone may remove synonyms that are not used in practice; only names that need to be processed as synonyms for compatibility with legacy content are to be registered in this way.
One of the following:
If a metadata name is found to be redundant with existing values, it should be removed and listed as a synonym for the existing value.
If a metadata name is added in the "proposed" state for a period of a month or more without being used or specified, then it may be removed from the WHATWG Wiki MetaExtensions page.
If a metadata name is added with the "proposed" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value. If a metadata name is added with the "proposed" status and found to be harmful, then it should be changed to "discontinued" status.
Anyone can change the status at any time, but should only do so in accordance with the definitions above.
The http-equiv attribute is an enumerated
attribute with the following keywords and states:
| Keyword | Conforming | State | Brief description |
|---|---|---|---|
content-language
| No | Content language | Sets the pragma-set default language. |
content-type
| Encoding declaration | An alternative form of setting the charset.
| |
default-style
| Default style | Sets the name of the default CSS style sheet set. | |
refresh
| Refresh | Acts as a timed redirect. | |
set-cookie
| No | Set-Cookie | Has no effect. |
x-ua-compatible
| X-UA-Compatible | In practice, encourages Internet Explorer to more closely follow the specifications. | |
content-security-policy
| Content security policy | Enforces a Content Security
Policy on a Document.
|
When a meta element is inserted
into the document, if its http-equiv attribute is
present and represents one of the above states, then the user agent must run the algorithm
appropriate for that state, as described in the following list:
http-equiv="content-language")
http-equiv="content-type")
The Encoding declaration state is
just an alternative form of setting the charset
attribute: it is a character encoding declaration. This state's user
agent requirements are all handled by the parsing section of the specification.
For meta elements with an http-equiv
attribute in the Encoding declaration
state, the content attribute must have a value
that is an ASCII case-insensitive match for a string that consists of:
"text/html;", optionally followed by any number of ASCII
whitespace, followed by "charset=utf-8".
A document must not contain both a meta element with an http-equiv attribute in the Encoding declaration state and a
meta element with the charset attribute
present.
The Encoding declaration state may be
used in HTML documents, but elements with an http-equiv attribute in that state must not be used in
XML documents.
http-equiv="default-style")
Support in one engine only.
This pragma sets the name of the default CSS style sheet set.
If the meta element has no content
attribute, or if that attribute's value is the empty string, then return.
Change the preferred CSS style sheet set name with the name being the value
of the element's content attribute.
[CSSOM]
http-equiv="refresh")
This pragma acts as a timed redirect.
For meta elements with an http-equiv attribute in the Refresh state, the content attribute must have a value consisting either of:
URL",
followed by a U+003D EQUALS SIGN character (=), followed by a valid URL string
that does not start with a literal U+0027 APOSTROPHE (') or U+0022 QUOTATION MARK (")
character.In the former case, the integer represents a number of seconds before the page is to be reloaded; in the latter case the integer represents a number of seconds before the page is to be replaced by the page at the given URL.
http-equiv="set-cookie")
This pragma is non-conforming and has no effect.
User agents are required to ignore this pragma.
http-equiv="x-ua-compatible")
In practice, this pragma encourages Internet Explorer to more closely follow the specifications.
For meta elements with an http-equiv
attribute in the X-UA-Compatible state, the
content attribute must have a value that is an
ASCII case-insensitive match for the string "IE=edge".
User agents are required to ignore this pragma.
http-equiv="content-security-policy")
This pragma enforces a Content Security
Policy on a Document. [CSP]
If the meta element is not a child of a head element,
return.
If the meta element has no content
attribute, or if that attribute's value is the empty string, then return.
Let policy be the result of executing Content Security Policy's parse
a serialized Content Security Policy algorithm on the meta element's
content attribute's value, with a source of "meta",
and a disposition of "enforce".
Remove all occurrences of the report-uri, frame-ancestors, and sandbox directives from policy.
Enforce the policy policy.
For meta elements with an http-equiv
attribute in the Content security
policy state, the content attribute must have a
value consisting of a valid Content Security
Policy, but must not contain any report-uri,
frame-ancestors, or sandbox directives.
The Content Security Policy given in the content attribute will be enforced upon the current document. [CSP]
There must not be more than one meta element with any particular state in the
document at a time.
The Encoding standard requires use of the UTF-8 character
encoding and requires use of the "utf-8" encoding label
to identify it. Those requirements necessitate that the document's character encoding
declaration, if it exists, specifies an encoding label using an ASCII
case-insensitive match for "utf-8". Regardless of whether a
character encoding declaration is present or not, the actual character encoding used to encode the document must be
UTF-8. [ENCODING]
To enforce the above rules, authoring tools must default to using UTF-8 for newly-created documents.
The following restrictions also apply:
In addition, due to a number of restrictions on meta elements, there can only be
one meta-based character encoding declaration per document.
If an HTML document does not start with a BOM, and its
encoding is not explicitly given by Content-Type
metadata, and the document is not an iframe srcdoc document, then the encoding must be specified
using a meta element with a charset attribute
or a meta element with an http-equiv
attribute in the Encoding declaration
state.
If the document is an iframe srcdoc
document, the document must not have a character encoding declaration. (In
this case, the source is already decoded, since it is part of the document that contained the
iframe.)
In XML, the XML declaration should be used for inline character encoding information, if necessary.
style elementSupport in all current engines.
Support in all current engines.
noscript element that is a child of a head element.media — Applicable media
blocking — Whether the element is potentially render-blocking
title attribute has special semantics on this element: CSS style sheet set name
The style element allows authors to embed CSS style sheets in their documents.
The style element is one of several inputs to the styling processing
model. The element does not represent content for the
user.
Support in all current engines.
The disabled setter steps are:
If this does not have an associated CSS style sheet, return.
If the given value is true, set this's associated CSS style sheet's disabled flag. Otherwise, unset this's associated CSS style sheet's disabled flag.
The default, if the media
attribute is omitted, is "all", meaning that by default styles apply to all
media.
The blocking
attribute is a blocking attribute.
Support in one engine only.
The child text content of a style element must be that of a
conformant style sheet.
A style element is implicitly potentially render-blocking if the
element was created by its node document's parser.
The user agent must run the update a style block algorithm whenever
any of the following conditions occur:
The element is popped off the stack of open elements of an HTML parser or XML parser.
The element is not on the stack of open elements of an HTML parser or XML parser, and it becomes connected or disconnected.
The element's children changed steps run.
Once the attempts to obtain the style sheet's critical subresources, if any, are complete, or, if the style sheet has no critical subresources, once the style sheet has been parsed and processed, the user agent must run these steps:
Let element be the style element associated with the style sheet
in question.
Let success be true.
If the attempts to obtain any of the style sheet's critical subresources failed for any reason (e.g., DNS error, HTTP 404 response, a connection being prematurely closed, unsupported Content-Type), set success to false.
Queue an element task on the networking task source given element and the following steps:
If success is true, fire an event
named load at element.
Otherwise, fire an event named error at element.
If element contributes a script-blocking style sheet:
Assert: element's node document's script-blocking style sheet set contains element.
Remove element from its node document's script-blocking style sheet set.
Unblock rendering on element.
The element must delay the load event of the element's node document until all the attempts to obtain the style sheet's critical subresources, if any, are complete.
Support in all current engines.
The LinkStyle interface is also implemented by this element. [CSSOM]
If the style sheet referenced no other resources (e.g., it was an internal style sheet given by
a style element with no @import rules), then the style rules
must be immediately made available to script; otherwise, the style rules must only be
made available to script once the event loop reaches its update the
rendering step.
A Document has no style sheet that is blocking scripts if it does not
have a style sheet that is blocking
scripts.
Introduction_to_HTML/Document_and_website_structure#HTML_for_structuring_content
Support in all current engines.
body elementSupport in all current engines.
Support in all current engines.
html element.body element's start tag can be omitted
if the element is empty, or if the first thing inside the body element is not
ASCII whitespace or a comment, except if the
first thing inside the body element is a meta, noscript,
link, script, style, or template element.
body element's end tag can be omitted if the
body element is not immediately followed by a comment.onafterprintonbeforeprintonbeforeunloadonhashchangeonlanguagechangeonmessageonmessageerroronofflineononlineonpageswaponpagehideonpagerevealonpageshowonpopstateonrejectionhandledonstorageonunhandledrejectiononunloadThe body element represents the contents of the document.
In conforming documents, there is only one body element. The document.body IDL attribute provides scripts with easy access to
a document's body element.
The body element exposes as event handler content attributes a number
of the event handlers of the Window object. It also mirrors their
event handler IDL attributes.
The event handlers of the Window object named by the
Window-reflecting body element event handler set, exposed on the
body element, replace the generic event handlers with the same names
normally supported by HTML elements.
article elementSupport in all current engines.
HTMLElement.The article element represents a complete, or self-contained,
composition in a document, page, application, or site and that is, in principle, independently
distributable or reusable, e.g. in syndication. This could be a forum post, a magazine or
newspaper article, a blog entry, a user-submitted comment, an interactive widget or gadget, or any
other independent item of content.
When article elements are nested, the inner article elements
represent articles that are in principle related to the contents of the outer article. For
instance, a blog entry on a site that accepts user-submitted comments could represent the comments
as article elements nested within the article element for the blog
entry.
Author information associated with an article element (q.v. the
address element) does not apply to nested article elements.
When the main content of the page (i.e. excluding footers, headers, navigation blocks, and
sidebars) is all one single self-contained composition, that content may be marked with an
article, but it is technically redundant in that case (since it's self-evident that
the page is a single composition, as it is a single document).
section elementSupport in all current engines.
HTMLElement.The section element represents a generic section of a document or
application. A section, in this context, is a thematic grouping of content, typically with a
heading.
nav elementSupport in all current engines.
HTMLElement.The nav element represents a section of a page that links to other
pages or to parts within the page: a section with navigation links.
aside elementSupport in all current engines.
HTMLElement.The aside element represents a section of a page that consists of
content that is tangentially related to the content around the aside element, and
which could be considered separate from that content. Such sections are often represented as
sidebars in printed typography.
The element can be used for typographical effects like pull quotes or sidebars, for
advertising, for groups of nav elements, and for other content that is considered
separate from the main content of the page.
h1, h2, h3, h4, h5, and h6
elementsSupport in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
hgroup element.These elements represent headings for their sections.
The semantics and meaning of these elements are defined in the section on headings and outlines.
These elements have a heading level given by the number in their name. The
heading level corresponds to the levels of nested sections. The h1
element is for a top-level section, h2 for a subsection, h3 for a
sub-subsection, and so on.
hgroup elementSupport in all current engines.
p elements, followed by one h1, h2,
h3, h4, h5, or h6 element, followed by zero
or more p elements, optionally intermixed with script-supporting
elements.HTMLElement.The hgroup element represents a heading and related content. The
element may be used to group an h1–h6 element with one or more
p elements containing content representing a subheading, alternative title, or
tagline.
header elementSupport in all current engines.
header or footer element
descendants.HTMLElement.The header element represents a group of introductory or navigational
aids.
footer elementSupport in all current engines.
header or footer element
descendants.HTMLElement.The footer element represents a footer for its nearest ancestor
sectioning content element, or for the body element if there is no such
ancestor. A footer typically contains information about its section such as who wrote it, links
to related documents, copyright data, and the like.
When the footer element contains entire sections, they represent appendices, indices, long colophons, verbose license
agreements, and other such content.
Footers don't necessarily have to appear at the end of a section, though they usually do.
When there is no ancestor sectioning content element, then it applies to the whole page.
address elementSupport in all current engines.
header, footer, or
address element descendants.HTMLElement.The address element represents the contact information for its
nearest article or body element ancestor. If that is the body
element, then the contact information applies to the document as a whole.
The address element must not be used to represent arbitrary addresses (e.g. postal
addresses), unless those addresses are in fact the relevant contact information. (The
p element is the appropriate element for marking up postal addresses in general.)
The address element must not contain information other than contact
information.
Typically, the address element would be included along with other information in a
footer element.
The contact information for a node node is a collection of
address elements defined by the first applicable entry from the following list:
article elementbody elementThe contact information consists of all the address elements that have node as an ancestor and do not have another body or
article element ancestor that is a descendant of node.
article elementbody elementThe contact information of node is the same as the contact information of
the nearest article or body element ancestor, whichever is
nearest.
The contact information of node is the same as the contact information of
the body element of the Document.
There is no contact information for node.
User agents may expose the contact information of a node to the user, or use it for other purposes, such as indexing sections based on the sections' contact information.
The outline should be used for generating document outlines, for example when generating tables of contents. When creating an interactive table of contents, entries should jump the user to the relevant heading.
If a document has one or more headings, at least a single heading within the outline should have a heading level of 1.
Each heading following another heading lead in the outline must have a heading level that is less than, equal to, or 1 greater than lead's heading level.
User agents are encouraged to expose page outlines to users to aid in navigation. This is especially true for non-visual media, e.g. screen readers.
This section is non-normative.
| Element | Purpose |
|---|---|
| Example | |
body
| The contents of the document. |
article
| A complete, or self-contained, composition in a document, page, application, or site and that is, in principle, independently distributable or reusable, e.g. in syndication. This could be a forum post, a magazine or newspaper article, a blog entry, a user-submitted comment, an interactive widget or gadget, or any other independent item of content. |
section
| A generic section of a document or application. A section, in this context, is a thematic grouping of content, typically with a heading. |
nav
| A section of a page that links to other pages or to parts within the page: a section with navigation links. |
aside
| A section of a page that consists of
content that is tangentially related to the content around the aside element, and
which could be considered separate from that content. Such sections are often represented as
sidebars in printed typography.
|
h1–h6
| A heading |
hgroup
| A heading and related content. The
element may be used to group an h1–h6 element with one or more
p elements containing content representing a subheading, alternative title, or
tagline.
|
header
| A group of introductory or navigational aids. |
footer
| A footer for its nearest ancestor sectioning content element, or for the body element if there is no such ancestor. A footer typically contains information about its section such as who wrote it, links to related documents, copyright data, and the like. |
This section is non-normative.
A section forms part of something else. An article is its own thing.
But how does one know which is which? Mostly the real answer is "it depends on author intent".
For example, one could imagine a book with a "Granny Smith" chapter that just said "These
juicy, green apples make a great filling for apple pies."; that would be a section
because there'd be lots of other chapters on (maybe) other kinds of apples.
On the other hand, one could imagine a tweet or reddit comment or tumblr post or newspaper
classified ad that just said "Granny Smith. These juicy, green apples make a great filling for
apple pies."; it would then be articles because that was the whole thing.
A comment on an article is not part of the article on which it is commenting,
therefore it is its own article.
p elementSupport in all current engines.
Support in all current engines.
p element's end tag can be omitted if the
p element is immediately followed by an address, article,
aside, blockquote, details, dialog,
div, dl, fieldset, figcaption,
figure, footer, form, h1, h2,
h3, h4, h5, h6, header,
hgroup, hr, main, menu, nav,
ol, p, pre, search, section,
table, or ul element, or if there is no more content in the parent
element and the parent element is an HTML element that is not
an a, audio, del, ins, map,
noscript, or video element, or an autonomous custom
element.The p element represents a paragraph.
The p element should not be used when a more specific element is more
appropriate.
hr elementSupport in all current engines.
Support in all current engines.
select element.The hr element represents a paragraph-level thematic
break, e.g., a scene change in a story, or a transition to another topic within a section of a
reference book; alternatively, it represents a separator between a set of options of a
select element.
pre elementSupport in all current engines.
Support in all current engines.
The pre element represents a block of preformatted text, in which
structure is represented by typographic conventions rather than by elements.
Some examples of cases where the pre element could be used:
To represent a block of computer code, the pre element can be used with a
code element; to represent a block of computer output the pre element
can be used with a samp element. Similarly, the kbd element can be used
within a pre element to indicate text that the user is to enter.
blockquote elementSupport in all current engines.
Support in all current engines.
cite — Link to the source of the quotation or more information about the edit
The blockquote element represents a section that is quoted from
another source.
If the cite attribute is present, it must be a
valid URL potentially surrounded by spaces. To obtain the
corresponding citation link, the value of the attribute must be parsed relative to the element's node document. User agents may
allow users to follow such citation links, but they are primarily intended for private use (e.g.,
by server-side scripts collecting statistics about a site's use of quotations), not for
readers.
The content of a blockquote may be abbreviated or may have context added in the
conventional manner for the text's language.
Attribution for the quotation, if any, must be placed outside the blockquote
element.
The cite IDL
attribute must reflect the element's cite content
attribute.
ol elementSupport in all current engines.
Support in all current engines.
li element: Palpable content.li and script-supporting elements.reversed — Number the list backwards
start — Starting value of the list
type — Kind of list marker
The ol element represents a list of items, where the items have been
intentionally ordered, such that changing the order would change the meaning of the document.
The items of the list are the li element child nodes of the ol
element, in tree order.
Support in all current engines.
The type attribute can be
used to specify the kind of marker to use in the list, in the cases where that matters (e.g.
because items are to be referenced by their number/letter). The attribute, if
specified, must have a value that is identical to one of the characters given in the
first cell of one of the rows of the following table. The type attribute represents the state given in the cell in the second
column of the row whose first cell matches the attribute's value; if none of the cells match, or
if the attribute is omitted, then the attribute represents the decimal state.
| Keyword | State | Description | Examples for values 1-3 and 3999-4001 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
1
(U+0031)
| decimal | Decimal numbers | 1. | 2. | 3. | ... | 3999. | 4000. | 4001. | ... |
a (U+0061)
| lower-alpha | Lowercase latin alphabet | a. | b. | c. | ... | ewu. | ewv. | eww. | ... |
A (U+0041)
| upper-alpha | Uppercase latin alphabet | A. | B. | C. | ... | EWU. | EWV. | EWW. | ... |
i (U+0069)
| lower-roman | Lowercase roman numerals | i. | ii. | iii. | ... | mmmcmxcix. | i̅v̅. | i̅v̅i. | ... |
I (U+0049)
| upper-roman | Uppercase roman numerals | I. | II. | III. | ... | MMMCMXCIX. | I̅V̅. | I̅V̅I. | ... |
User agents should render the items of the list in a manner consistent with the state of the
type attribute of the ol element. Numbers less than
or equal to zero should always use the decimal system regardless of the type attribute.
The start IDL
attribute must reflect the content attribute of the same name, with a default
value of 1.
ul elementSupport in all current engines.
Support in all current engines.
li element: Palpable content.li and script-supporting elements.The ul element represents a list of items, where the order of the
items is not important — that is, where changing the order would not materially change the
meaning of the document.
The items of the list are the li element child nodes of the ul
element.
menu elementSupport in all current engines.
Support in all current engines.
li element: Palpable content.li and script-supporting elements.The menu element represents a toolbar consisting of its contents, in
the form of an unordered list of items (represented by li elements), each of
which represents a command that the user can perform or activate.
li elementSupport in all current engines.
Support in all current engines.
ol elements.ul elements.menu elements.li element's end tag can be omitted if the
li element is immediately followed by another li element or if there is
no more content in the parent element.ul or menu element: value — Ordinal value of the list item
The li element represents a list item. If its parent element is an
ol, ul, or menu element, then the element is an item of the
parent element's list, as defined for those elements. Otherwise, the list item has no defined
list-related relationship to any other li element.
The value attribute, if
present, must be a valid integer. It is used to determine the ordinal
value of the list item, when the li's list owner is an
ol element.
The value IDL
attribute must reflect the value of the value
content attribute.
dl elementSupport in all current engines.
Support in all current engines.
dt elements followed by one or more dd elements, optionally intermixed with script-supporting elements.div elements, optionally intermixed with script-supporting elements.The dl element represents an association list consisting of zero or
more name-value groups (a description list). A name-value group consists of one or more names
(dt elements, possibly as children of a div element child) followed by
one or more values (dd elements, possibly as children of a div element
child), ignoring any nodes other than dt and dd element children, and
dt and dd elements that are children of div element
children. Within a single dl element, there should not be more than one
dt element for each name.
Name-value groups may be terms and definitions, metadata topics and values, questions and answers, or any other groups of name-value data.
The values within a group are alternatives; multiple paragraphs forming part of the same value
must all be given within the same dd element.
The order of the list of groups, and of the names and values within each group, may be significant.
In order to annotate groups with microdata attributes, or other global
attributes that apply to whole groups, or just for styling purposes, each group in a
dl element can be wrapped in a div element. This does not change the
semantics of the dl element.
The name-value groups of a dl element dl are determined using the
following algorithm. A name-value group has a name (a list of dt elements, initially
empty) and a value (a list of dd elements, initially empty).
Let groups be an empty list of name-value groups.
Let current be a new name-value group.
Let seenDd be false.
Let child be dl's first child.
Let grandchild be null.
While child is not null:
If child is a div element, then:
Let grandchild be child's first child.
While grandchild is not null:
Process dt or dd for
grandchild.
Set grandchild to grandchild's next sibling.
Otherwise, process dt or dd for
child.
Set child to child's next sibling.
If current is not empty, then append current to groups.
Return groups.
dt elementSupport in all current engines.
dd or dt elements inside dl elements.dd or dt elements inside div elements that are children of a dl element.header, footer, sectioning content, or heading content descendants.dt element's end tag can be omitted if the
dt element is immediately followed by another dt element or a
dd element.HTMLElement.The dt element represents the term, or name, part of a
term-description group in a description list (dl element).
dd elementSupport in all current engines.
dt or dd elements inside dl elements.dt or dd elements inside div elements that are children of a dl element.dd element's end tag can be omitted if the
dd element is immediately followed by another dd element or a
dt element, or if there is no more content in the parent element.HTMLElement.The dd element represents the description, definition, or value, part
of a term-description group in a description list (dl element).
figure elementSupport in all current engines.
figcaption element followed by flow content.figcaption element.HTMLElement.The figure element represents some flow content,
optionally with a caption, that is self-contained (like a complete sentence) and is typically
referenced as a single unit from the main flow of the document.
The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc.
The first figcaption element child of the element, if any,
represents the caption of the figure element's contents. If there is no child
figcaption element, then there is no caption.
A figure element's contents are part of the surrounding flow. If the purpose of
the page is to display the figure, for example a photograph on an image sharing site, the
figure and figcaption elements can be used to explicitly provide a
caption for that figure. For content that is only tangentially related, or that serves a separate
purpose than the surrounding flow, the aside element should be used (and can itself
wrap a figure). For example, a pull quote that repeats content from an
article would be more appropriate in an aside than in a
figure, because it isn't part of the content, it's a repetition of the content for
the purposes of enticing readers or highlighting key topics.
figcaption elementSupport in all current engines.
figure element.HTMLElement.The figcaption element represents a caption or legend for the rest of
the contents of the figcaption element's parent figure element, if any.
main elementSupport in all current engines.
main element.HTMLElement.The main element represents the dominant contents of the
document.
A document must not have more than one main element that does not have the attribute specified.
A hierarchically correct main element is one whose ancestor elements
are limited to html, body, div, form without
an accessible name, and autonomous custom elements. Each main element must be a
hierarchically correct main element.
search elementNo support in current engines.
HTMLElement.The search element represents a part of a document or application
that contains a set of form controls or other content related to performing a search or filtering
operation. This could be a search of the web site or application; a way of searching or filtering
search results on the current web page; or a global or Internet-wide search function.
div elementSupport in all current engines.
Support in all current engines.
dl element.dl element: one or more dt elements followed by one or more dd elements, optionally intermixed with script-supporting elements.dl element: flow content.The div element has no special meaning at all. It represents its
children. It can be used with the class, lang, and title attributes to mark up
semantics common to a group of consecutive elements. It can also be used in a dl
element, wrapping groups of dt and dd elements.
a elementSupport in all current engines.
Support in all current engines.
href attribute: Interactive content.a element descendant, or descendant with the tabindex attribute specified.href — Address of the hyperlink
target — Navigable for hyperlink navigation
download — Whether to download the resource instead of navigating to it, and its filename if so
ping — URLs to ping
rel — Relationship between the location in the document containing the hyperlink and the destination resource
hreflang — Language of the linked resource
type — Hint for the type of the referenced resource
referrerpolicy — Referrer policy for fetches initiated by the element
href attribute: for authors; for implementers.If the a element has an href attribute,
then it represents a hyperlink (a hypertext anchor) labeled by its
contents.
If the a element has no href attribute,
then the element represents a placeholder for where a link might otherwise have been
placed, if it had been relevant, consisting of just the element's contents.
The target, download, ping,
rel, hreflang, type,
and referrerpolicy attributes must be omitted
if the href attribute is not present.
If the itemprop attribute is specified on an a element,
then the href attribute must also be specified.
The href, target, download, ping,
and referrerpolicy attributes affect what
happens when users follow hyperlinks or download hyperlinks created using the a
element. The rel, hreflang, and type
attributes may be used to indicate to the user the likely nature of the target resource before the
user follows the link.
Support in all current engines.
Support in all current engines.
The IDL attributes download, ping, target, rel, hreflang, and type, must reflect the respective content attributes
of the same name.
Support in all current engines.
The IDL attribute relList must reflect the rel content attribute.
HTMLAnchorElement/referrerPolicy
Support in all current engines.
The text attribute's setter must string replace
all with the given value within this element.
em elementSupport in all current engines.
HTMLElement.The em element represents stress emphasis of its contents.
The level of stress that a particular piece of content has is given by its number of ancestor
em elements.
The placement of stress emphasis changes the meaning of the sentence. The element thus forms an integral part of the content. The precise way in which stress is used in this way depends on the language.
strong elementSupport in all current engines.
HTMLElement.The strong element represents strong importance, seriousness, or
urgency for its contents.
Importance: the strong element can be used in a heading, caption,
or paragraph to distinguish the part that really matters from other parts that might be more
detailed, more jovial, or merely boilerplate. (This is distinct from marking up subheadings, for
which the hgroup element is appropriate.)
Seriousness: the strong element can be used to mark up a warning
or caution notice.
Urgency: the strong element can be used to denote contents that
the user needs to see sooner than other parts of the document.
The relative level of importance of a piece of content is given by its number of ancestor
strong elements; each strong element increases the importance of its
contents.
Changing the importance of a piece of text with the strong element does not change
the meaning of the sentence.
small elementSupport in all current engines.
HTMLElement.The small element represents side comments such as small print.
The small element should not be used for extended spans of text, such as multiple
paragraphs, lists, or sections of text. It is only intended for short runs of text. The text of a
page listing terms of use, for instance, would not be a suitable candidate for the
small element: in such a case, the text is not a side comment, it is the main content
of the page.
The small element must not be used for subheadings; for that purpose, use the
hgroup element.
s elementSupport in all current engines.
HTMLElement.The s element represents contents that are no longer accurate or no
longer relevant.
cite elementSupport in all current engines.
HTMLElement.The cite element represents the title of a work (e.g.
a book,
a paper,
an essay,
a poem,
a score,
a song,
a script,
a film,
a TV show,
a game,
a sculpture,
a painting,
a theatre production,
a play,
an opera,
a musical,
an exhibition,
a legal case report,
a computer program,
etc.). This can be a work that is being quoted or referenced in detail (i.e., a
citation), or it can just be a work that is mentioned in passing.
A person's name is not the title of a work — even if people call that person a piece of
work — and the element must therefore not be used to mark up people's names. (In some cases,
the b element might be appropriate for names; e.g. in a gossip article where the
names of famous people are keywords rendered with a different style to draw attention to them. In
other cases, if an element is really needed, the span element can be
used.)
q elementSupport in all current engines.
cite — Link to the source of the quotation or more information about the edit
HTMLQuoteElement.The q element represents some phrasing
content quoted from another source.
Quotation punctuation (such as quotation marks) that is quoting the contents of the element
must not appear immediately before, after, or inside q elements; they will be
inserted into the rendering by the user agent.
If the cite attribute is present, it must be a valid
URL potentially surrounded by spaces. To obtain the corresponding citation
link, the value of the attribute must be parsed
relative to the element's node document. User agents may allow users to follow
such citation links, but they are primarily intended for private use (e.g., by server-side scripts
collecting statistics about a site's use of quotations), not for readers.
The q element must not be used in place of quotation marks that do not represent
quotes; for example, it is inappropriate to use the q element for marking up
sarcastic statements.
The use of q elements to mark up quotations is entirely optional; using explicit
quotation punctuation without q elements is just as correct.
dfn elementSupport in all current engines.
dfn element descendants.title attribute has special semantics on this element: Full term or expansion of abbreviation
HTMLElement.The dfn element represents the defining instance of a term. The paragraph, description list group, or section that is the nearest ancestor of the dfn
element must also contain the definition(s) for the term given
by the dfn element.
Defining term: if the dfn element has a title attribute, then the exact value of that
attribute is the term being defined. Otherwise, if it contains exactly one element child node and
no child Text nodes, and that child element is an abbr element with a
title attribute, then the exact value of that
attribute is the term being defined. Otherwise, it is the descendant text content of
the dfn element that gives the term being defined.
If the title attribute of the dfn element is
present, then it must contain only the term being defined.
An a element that links to a dfn element represents an instance of
the term defined by the dfn element.
abbr elementSupport in all current engines.
title attribute has special semantics on this element: Full term or expansion of abbreviation
HTMLElement.If an abbreviation is pluralized, the expansion's grammatical number (plural vs singular) must match the grammatical number of the contents of the element.
Abbreviations do not have to be marked up using this element. It is expected to be useful in the following cases:
abbr element with a title attribute is an
alternative to including the expansion inline (e.g. in parentheses).abbr element with a title attribute or include the expansion inline in the text the first
time the abbreviation is used.abbr element
can be used without a title attribute.ruby elementSupport in all current engines.
HTMLElement.The ruby element allows one or more spans of phrasing content to be marked with
ruby annotations. Ruby annotations are short runs of text presented alongside base text, primarily
used in East Asian typography as a guide for pronunciation or to include other annotations. In
Japanese, this form of typography is also known as furigana.
The content model of ruby elements consists of one or more of the following
sequences:
One or the other of the following:
Phrasing content, but with no ruby elements and with no
ruby element descendants
A single ruby element that itself has no ruby element
descendants
One or the other of the following:
The ruby and rt elements can be used for a variety of kinds of
annotations, including in particular (though by no means limited to) those described below. For
more details on Japanese Ruby in particular, and how to render Ruby for Japanese, see
Requirements for Japanese Text Layout. [JLREQ]
One or more hiragana or katakana characters (the ruby annotation) are placed with each ideographic character (the base text). This is used to provide readings of kanji characters.
This is similar to the previous case: each ideographic character in the compound word (the base text) has its reading given in hiragana or katakana characters (the ruby annotation). The difference is that the base text segments form a compound word rather than being separate from each other.
This is semantically identical to the previous case (each individual ideographic character in the base compound word has its reading given in an annotation in hiragana or katakana characters), but the rendering is the more complicated Jukugo Ruby rendering.
The annotation describes the meaning of the base text, rather than (or in addition to) the pronunciation. As such, both the base text and the annotation can be multiple characters long.
A phonetic reading that corresponds to multiple base characters, because a one-to-one mapping would be difficult. (In English, the words "Colonel" and "Lieutenant" are examples of words where a direct mapping of pronunciation to individual letters is, in some dialects, rather unclear.)
Sometimes, ruby styles described above are combined.
If this results in two annotations covering the same single base segment, then the annotations can just be placed back to back.
In more complicated situations such as the following examples, a nested ruby
element is used to give the inner annotations, and then that whole ruby is then
given an annotation at the "outer" level.
Within a ruby element that does not have a ruby element ancestor,
content is segmented and segments are placed into three categories: base text segments, annotation
segments, and ignored segments. Ignored segments do not form part of the document's semantics
(they consist of some inter-element whitespace and rp elements, the
latter of which are used for legacy user agents that do not support ruby at all). Base text
segments can overlap (with a limit of two segments overlapping any one position in the DOM, and
with any segment having an earlier start point than an overlapping segment also having an equal or
later end point, and any segment have a later end point than an overlapping segment also having an
equal or earlier start point). Annotation segments correspond to rt elements. Each annotation
segment can be associated with a base text segment, and each base text segment can have annotation
segments associated with it. (In a conforming document, each base text segment is associated with
at least one annotation segment, and each annotation segment is associated with one base text
segment.) A ruby element represents the union of the segments of base
text it contains, along with the mapping from those base text segments to annotation segments.
Segments are described in terms of DOM ranges; annotation segment ranges always
consist of exactly one element. [DOM]
At any particular time, the segmentation and categorization of content of a ruby
element is the result that would be obtained from running the following algorithm:
Let base text segments be an empty list of base text segments, each potentially with a list of base text subsegments.
Let annotation segments be an empty list of annotation segments, each potentially being associated with a base text segment or subsegment.
Let root be the ruby element for which the algorithm is
being run.
If root has a ruby element ancestor, then jump to the
step labeled end.
Let current parent be root.
Let index be 0.
Let start index be null.
Let parent start index be null.
Let current base text be null.
Start mode: If index is greater than or equal to the number of child nodes in current parent, then jump to the step labeled end mode.
If the indexth node in current parent is an
rt or rp element, jump to the step labeled annotation
mode.
Set start index to the value of index.
Base mode: If the indexth node in current
parent is a ruby element, and if current parent is the
same element as root, then push a ruby level and then jump to
the step labeled start mode.
If the indexth node in current parent is an
rt or rp element, then set the current base text and then
jump to the step labeled annotation mode.
Increment index by one.
Base mode post-increment: If index is greater than or equal to the number of child nodes in current parent, then jump to the step labeled end mode.
Jump back to the step labeled base mode.
Annotation mode: If the indexth node in current
parent is an rt element, then push a ruby annotation and jump to
the step labeled annotation mode increment.
If the indexth node in current parent is an
rp element, jump to the step labeled annotation mode increment.
If the indexth node in current parent is not a
Text node, or is a Text node that is not inter-element
whitespace, then jump to the step labeled base mode.
Annotation mode increment: Let lookahead index be index plus one.
Annotation mode white-space skipper: If lookahead index is equal to the number of child nodes in current parent then jump to the step labeled end mode.
If the lookahead indexth node in current parent is
an rt element or an rp element, then set index to
lookahead index and jump to the step labeled annotation mode.
If the lookahead indexth node in current parent is
not a Text node, or is a Text node that is not inter-element
whitespace, then jump to the step labeled base mode (without further incrementing
index, so the inter-element whitespace seen so far becomes part
of the next base text segment).
Increment lookahead index by one.
Jump to the step labeled annotation mode white-space skipper.
End mode: If current parent is not the same element as root, then pop a ruby level and jump to the step labeled base mode post-increment.
End: Return base text segments and annotation
segments. Any content of the ruby element not described by segments in either
of those lists is implicitly in an ignored segment.
rt elementSupport in all current engines.
ruby element.rt element's end tag can be omitted if the
rt element is immediately followed by an rt or rp element,
or if there is no more content in the parent element.HTMLElement.The rt element marks the ruby text component of a ruby annotation. When it is the
child of a ruby element, it doesn't represent
anything itself, but the ruby element uses it as part of determining what it
represents.
An rt element that is not a child of a ruby element
represents the same thing as its children.
rp elementSupport in all current engines.
ruby element, either immediately before or immediately after an rt element.rp element's end tag can be omitted if the
rp element is immediately followed by an rt or rp element,
or if there is no more content in the parent element.HTMLElement.The rp element can be used to provide parentheses or other content around a ruby
text component of a ruby annotation, to be shown by user agents that don't support ruby
annotations.
An rp element that is a child of a ruby
element represents nothing. An rp element
whose parent element is not a ruby element represents its
children.
data elementSupport in all current engines.
Support in all current engines.
value — Machine-readable value
The data element represents its contents, along with a
machine-readable form of those contents in the value
attribute.
The element can be used for several purposes.
When combined with microformats or the microdata attributes defined in
this specification, the element serves to provide both a machine-readable value for the purposes
of data processors, and a human-readable value for the purposes of rendering in a web browser. In
this case, the format to be used in the value attribute is
determined by the microformats or microdata vocabulary in use.
The element can also, however, be used in conjunction with scripts in the page, for when a
script has a literal value to store alongside a human-readable value. In such cases, the format to
be used depends only on the needs of the script. (The data-*
attributes can also be useful in such situations.)
Support in all current engines.
The value IDL
attribute must reflect the content attribute of the same name.
time elementSupport in all current engines.
Support in all current engines.
datetime attribute: Phrasing content.datetime — Machine-readable value
The time element represents its contents, along with a
machine-readable form of those contents in the datetime
attribute. The kind of content is limited to various kinds of dates, times, time-zone offsets, and
durations, as described below.
A time element that does not have a datetime content attribute must not have any element
descendants.
The datetime value of a time element must match one of the following
syntaxes.
Support in all current engines.
The dateTime
IDL attribute must reflect the element's datetime content attribute.
code elementSupport in all current engines.
HTMLElement.The code element represents a fragment of computer code. This could
be an XML element name, a filename, a computer program, or any other string that a computer would
recognize.
There is no formal way to indicate the language of computer code being marked up. Authors who
wish to mark code elements with the language used, e.g. so that syntax highlighting
scripts can use the right rules, can use the class attribute, e.g.
by adding a class prefixed with "language-" to the element.
var elementSupport in all current engines.
HTMLElement.The var element represents a variable. This could be an actual
variable in a mathematical expression or programming context, an identifier representing a
constant, a symbol identifying a physical quantity, a function parameter, or just be a term used
as a placeholder in prose.
For mathematics, in particular for anything beyond the simplest of expressions, MathML is more
appropriate. However, the var element can still be used to refer to specific
variables that are then mentioned in MathML expressions.
samp elementSupport in all current engines.
HTMLElement.The samp element represents sample or quoted output from another
program or computing system.
kbd elementSupport in all current engines.
HTMLElement.The kbd element represents user input (typically keyboard input,
although it may also be used to represent other input, such as voice commands).
When the kbd element is nested inside a samp element, it represents
the input as it was echoed by the system.
When the kbd element contains a samp element, it represents
input based on system output, for example invoking a menu item.
When the kbd element is nested inside another kbd element, it
represents an actual key or other single unit of input as appropriate for the input mechanism.
sub and sup elementsSupport in all current engines.
Support in all current engines.
sub element: for authors; for implementers.sup element: for authors; for implementers.HTMLElement.The sup element represents a superscript and the sub
element represents a subscript.
These elements must be used only to mark up typographical conventions with specific meanings,
not for typographical presentation for presentation's sake. For example, it would be inappropriate
for the sub and sup elements to be used in the name of the LaTeX
document preparation system. In general, authors should use these elements only if the
absence of those elements would change the meaning of the content.
In certain languages, superscripts are part of the typographical conventions for some abbreviations.
The sub element can be used inside a var element, for variables that
have subscripts.
Mathematical expressions often use subscripts and superscripts. Authors are encouraged to use
MathML for marking up mathematics, but authors may opt to use sub and
sup if detailed mathematical markup is not desired. [MATHML]
i elementSupport in all current engines.
HTMLElement.The i element represents a span of text in an alternate voice or
mood, or otherwise offset from the normal prose in a manner indicating a different quality of
text, such as a taxonomic designation, a technical term, an idiomatic phrase from another
language, transliteration, a thought, or a ship name in Western texts.
Terms in languages different from the main text should be annotated with lang attributes (or, in XML, lang attributes in the XML namespace).
Authors can use the class attribute on the i
element to identify why the element is being used, so that if the style of a particular use (e.g.
dream sequences as opposed to taxonomic terms) is to be changed at a later date, the author
doesn't have to go through the entire document (or series of related documents) annotating each
use.
Authors are encouraged to consider whether other elements might be more applicable than the
i element, for instance the em element for marking up stress emphasis,
or the dfn element to mark up the defining instance of a term.
b elementSupport in all current engines.
HTMLElement.The b element represents a span of text to which attention is being
drawn for utilitarian purposes without conveying any extra importance and with no implication of
an alternate voice or mood, such as key words in a document abstract, product names in a review,
actionable words in interactive text-driven software, or an article lede.
As with the i element, authors can use the class
attribute on the b element to identify why the element is being used, so that if the
style of a particular use is to be changed at a later date, the author doesn't have to go through
annotating each use.
The b element should be used as a last resort when no other element is more
appropriate. In particular, headings should use the h1 to h6 elements,
stress emphasis should use the em element, importance should be denoted with the
strong element, and text marked or highlighted should use the mark
element.
u elementSupport in all current engines.
HTMLElement.The u element represents a span of text with an unarticulated, though
explicitly rendered, non-textual annotation, such as labeling the text as being a proper name in
Chinese text (a Chinese proper name mark), or labeling the text as being misspelt.
In most cases, another element is likely to be more appropriate: for marking stress emphasis,
the em element should be used; for marking key words or phrases either the
b element or the mark element should be used, depending on the context;
for marking book titles, the cite element should be used; for labeling text with explicit textual annotations, the
ruby element should be used; for technical terms, taxonomic designation,
transliteration, a thought, or for labeling ship names in Western texts, the i
element should be used.
mark elementSupport in all current engines.
HTMLElement.The mark element represents a run of text in one document marked or
highlighted for reference purposes, due to its relevance in
another context. When used in a quotation or other block of text referred to from the prose, it
indicates a highlight that was not originally present but which has been added to bring the
reader's attention to a part of the text that might not have been considered important by the
original author when the block was originally written, but which is now under previously
unexpected scrutiny. When used in the main prose of a document, it indicates a part of the
document that has been highlighted due to its likely relevance to the user's current activity.
bdi elementSupport in all current engines.
dir global attribute has special semantics on this element.HTMLElement.The bdi element represents a span of text that is to be isolated from
its surroundings for the purposes of bidirectional text formatting. [BIDI]
bdo elementSupport in all current engines.
dir global attribute has special semantics on this element.HTMLElement.The bdo element represents explicit text directionality formatting
control for its children. It allows authors to override the Unicode bidirectional algorithm by
explicitly specifying a direction override. [BIDI]
Authors must specify the dir attribute on this element, with the
value ltr to specify a left-to-right override and with the value rtl to
specify a right-to-left override. The auto value must not be specified.
span elementSupport in all current engines.
Support in all current engines.
The span element doesn't mean anything on its own, but can be useful when used
together with the global attributes, e.g. class,
lang, or dir. It
represents its children.
br elementSupport in all current engines.
Support in all current engines.
The br element represents a line break.
br elements must be used only for line breaks that are actually part of the
content, as in poems or addresses.
br elements must not be used for separating thematic groups in a paragraph.
If a paragraph consists of nothing but a single br element, it
represents a placeholder blank line (e.g. as in a template). Such blank lines must not be used for
presentation purposes.
Any content inside br elements must not be considered part of the surrounding
text.
wbr elementSupport in all current engines.
HTMLElement.The wbr element represents a line break opportunity.
Any content inside wbr elements must not be considered part of the surrounding
text.
This section is non-normative.
| Element | Purpose | Example |
|---|---|---|
a
| Hyperlinks | |
em
| Stress emphasis | |
strong
| Importance | |
small
| Side comments | |
s
| Inaccurate text | |
cite
| Titles of works | |
q
| Quotations | |
dfn
| Defining instance | |
abbr
| Abbreviations | |
ruby, rt, rp
| Ruby annotations | |
data
| Machine-readable equivalent | |
time
| Machine-readable equivalent of date- or time-related data | |
code
| Computer code | |
var
| Variables | |
samp
| Computer output | |
kbd
| User input | |
sub
| Subscripts | |
sup
| Superscripts | |
i
| Alternative voice | |
b
| Keywords | |
u
| Annotations | |
mark
| Highlight | |
bdi
| Text directionality isolation | |
bdo
| Text directionality formatting | |
span
| Other | |
br
| Line break | |
wbr
| Line breaking opportunity |
Links are a conceptual construct, created by a, area,
form, and link elements, that represent
a connection between two resources, one of which is the current Document. There are
three kinds of links in HTML:
These are links to resources that are to be used to augment the current document, generally automatically processed by the user agent. All external resource links have a fetch and process the linked resource algorithm which describes how the resource is obtained.
These are links to other resources that are generally exposed to the user by the user agent so that the user can cause the user agent to navigate to those resources, e.g. to visit them in a browser or download them.
These are links to resources within the current document, used to give those resources special meaning or behavior.
For link elements with an href attribute and a
rel attribute, links must be created for the keywords of the
rel attribute, as defined for those keywords in the link types section.
Similarly, for a and area elements with an href attribute and a rel attribute, links must be created for the keywords of the
rel attribute as defined for those keywords in the link types section. Unlike link elements, however,
a and area elements with an href
attribute that either do not have a rel attribute, or
whose rel attribute has no keywords that are defined as
specifying hyperlinks, must also create a hyperlink.
This implied hyperlink has no special meaning (it has no link type)
beyond linking the element's node document to the resource given by the element's href attribute.
Similarly, for form elements with a rel
attribute, links must be created for the keywords of the rel
attribute as defined for those keywords in the link types section.
form elements that do not have a rel attribute,
or whose rel attribute has no keywords that are defined as
specifying hyperlinks, must also create a hyperlink.
A hyperlink can have one or more hyperlink annotations that modify the processing semantics of that hyperlink.
a and area elementsThe download
attribute, if present, indicates that the author intends the hyperlink to be used for downloading a resource. The attribute may have a value; the
value, if any, specifies the default filename that the author recommends for use in labeling the
resource in a local file system. There are no restrictions on allowed values, but authors are
cautioned that most file systems have limitations with regard to what punctuation is supported in
filenames, and user agents are likely to adjust filenames accordingly.
Support in all current engines.
rel's supported tokens are the keywords defined in HTML link types which are allowed on a and area
elements, impact the processing model, and are supported by the user agent. The possible supported tokens are noreferrer, noopener, and opener. rel's supported tokens must only include the tokens from this
list that the user agent implements the processing model for.
The rel attribute has no default value. If the
attribute is omitted or if none of the values in the attribute are recognized by the user agent,
then the document has no particular relationship with the destination resource other than there
being a hyperlink between the two.
The referrerpolicy attribute is a referrer
policy attribute. Its purpose is to set the referrer policy used when
following hyperlinks. [REFERRERPOLICY]
When an a or area element's activation behavior is
invoked, the user agent may allow the user to indicate a preference regarding whether the
hyperlink is to be used for navigation or whether the resource it
specifies is to be downloaded.
In the absence of a user preference, the default should be navigation if the element has no
download attribute, and should be to download the
specified resource if it does.
The activation behavior of an a or area element
element given an event event is:
If element has no href attribute,
then return.
Let hyperlinkSuffix be null.
If element is an a element, and event's target is an img with an ismap attribute specified, then:
Let x and y be 0.
If event's isTrusted attribute is
initialized to true, then set x to the distance in CSS
pixels from the left edge of the image to the location of the click, and set
y to the distance in CSS pixels from the top edge of the
image to the location of the click.
If x is negative, set x to 0.
If y is negative, set y to 0.
Set hyperlinkSuffix to the concatenation of U+003F (?), the value of x expressed as a base-ten integer using ASCII digits, U+002C (,), and the value of y expressed as a base-ten integer using ASCII digits.
Let userInvolvement be event's user navigation involvement.
If the user has expressed a preference to download the hyperlink, then set
userInvolvement to "browser UI".
If element has a download
attribute, or if the user has expressed a preference to download the hyperlink, then download the hyperlink created by element with
hyperlinkSuffix set to hyperlinkSuffix and
userInvolvement set to
userInvolvement.
Otherwise, follow the hyperlink created by element with hyperlinkSuffix set to hyperlinkSuffix and userInvolvement set to userInvolvement.
a and area elementsWhen elements implementing the HTMLHyperlinkElementUtils mixin are created, and
whenever those elements have their href content
attribute set, changed, or removed, the user agent must set the url.
To update href, set the element's href content attribute's value to the element's url, serialized.
The href setter steps are to set this's
href content attribute's value to the given value.
The protocol setter steps are:
Basic URL parse the given value, followed by ":", with this's url as
url and scheme start state as
state override.
The username setter steps are:
If url is null or url cannot have a username/password/port, then return.
Set the username, given url and the given value.
The password setter steps are:
If url is null or url cannot have a username/password/port, then return.
Set the password, given url and the given value.
The host setter steps are:
If url is null or url has an opaque path, then return.
Basic URL parse the given value, with url as url and host state as state override.
The hostname setter steps are:
If url is null or url has an opaque path, then return.
Basic URL parse the given value, with url as url and hostname state as state override.
The port setter steps are:
If url is null or url cannot have a username/password/port, then return.
If the given value is the empty string, then set url's port to null.
Otherwise, basic URL parse the given value, with url as url and port state as state override.
The pathname setter steps are:
If url is null or url has an opaque path, then return.
Set url's path to the empty list.
Basic URL parse the given value, with url as url and path start state as state override.
The search setter steps are:
If url is null, terminate these steps.
If the given value is the empty string, set url's query to null.
Otherwise:
Let input be the given value with a single leading "?"
removed, if any.
Set url's query to the empty string.
Basic URL parse input, with url as url and query state as state override.
The hash setter steps are:
If url is null, then return.
If the given value is the empty string, set url's fragment to null.
Otherwise:
Let input be the given value with a single leading "#"
removed, if any.
Set url's fragment to the empty string.
Basic URL parse input, with url as url and fragment state as state override.
To follow the hyperlink created by an element
subject, given an optional hyperlinkSuffix (default null) and an
optional userInvolvement (default "none"):
If subject cannot navigate, then return.
Let replace be false.
Let targetAttributeValue be the empty string.
If subject is an a or area element, then set
targetAttributeValue to the result of getting
an element's target given subject.
Let urlRecord be the result of encoding-parsing a URL given
subject's href attribute value, relative to
subject's node document.
If urlRecord is failure, then return.
Let noopener be the result of getting an element's noopener with subject, urlRecord, and targetAttributeValue.
Let targetNavigable be the first return value of applying the rules for choosing a navigable given targetAttributeValue, subject's node navigable, and noopener.
If targetNavigable is null, then return.
Let urlString be the result of applying the URL serializer to urlRecord.
If hyperlinkSuffix is non-null, then append it to urlString.
Let referrerPolicy be the current state of subject's referrerpolicy content attribute.
If subject's link
types includes the noreferrer keyword, then set
referrerPolicy to "no-referrer".
Navigate targetNavigable to urlString using subject's node document, with referrerPolicy set to referrerPolicy and userInvolvement set to userInvolvement.
Support in all current engines.
In some cases, resources are intended for later use rather than immediate viewing. To indicate
that a resource is intended to be downloaded for use later, rather than immediately used, the
download attribute can be specified on the
a or area element that creates the hyperlink to that
resource.
The attribute can furthermore be given a value, to specify the filename that user agents are
to use when storing the resource in a file system. This value can be overridden by the `Content-Disposition` HTTP header's filename parameters.
[RFC6266]
In cross-origin situations, the download
attribute has to be combined with the `Content-Disposition` HTTP header, specifically with the
attachment disposition type, to avoid the user being warned of possibly
nefarious activity. (This is to protect users from being made to download sensitive personal or
confidential information without their full understanding.)
To download the hyperlink created by an
element subject, given an optional hyperlinkSuffix (default null) and an
optional userInvolvement (default
"none"):
If subject cannot navigate, then return.
If subject's node document's active sandboxing flag set has the sandboxed downloads browsing context flag set, then return.
Let urlString be the result of encoding-parsing-and-serializing a
URL given subject's href attribute
value, relative to subject's node document.
If urlString is failure, then return.
If hyperlinkSuffix is non-null, then append it to urlString.
If userInvolvement is not "browser UI",
then:
Let navigation be subject's relevant global object's navigation API.
Let filename be the value of subject's download attribute.
Let continue be the result of firing a download request navigate event at
navigation with destinationURL
set to urlString, userInvolvement set to
userInvolvement, and filename set to
filename.
If continue is false, then return.
Run these steps in parallel:
Optionally, the user agent may abort these steps, if it believes doing so would safeguard the user from a potentially hostile download.
Let request be a new request whose
URL is urlString, client is entry settings object, initiator is "download", destination is the empty string, and whose
synchronous flag and use-URL-credentials flag are set.
Handle the result of fetching request as a download.
If the user agent needs a filename for a resource being handled as a download, it should select one using the following algorithm.
Let filename be the undefined value.
If the resource has a `Content-Disposition`
header, that header specifies the attachment disposition type, and the
header includes filename information, then let filename have the value specified by
the header, and jump to the step labeled sanitize below. [RFC6266]
Let interface origin be the origin of the Document in which the download or navigate action resulting in the
download was initiated, if any.
Let resource origin be the origin of the URL of the
resource being downloaded, unless that URL's scheme
component is data, in which case let resource origin be
the same as the interface origin, if any.
If there is no interface origin, then let trusted operation be true. Otherwise, let trusted operation be true if resource origin is the same origin as interface origin, and false otherwise.
If trusted operation is true and the resource has a `Content-Disposition` header and that header includes
filename information, then let filename have the value specified by the header, and
jump to the step labeled sanitize below. [RFC6266]
If the download was not initiated from a hyperlink created by an
a or area element, or if the element of the hyperlink from
which it was initiated did not have a download
attribute when the download was initiated, or if there was such an attribute but its value when
the download was initiated was the empty string, then jump to the step labeled no proposed
filename.
Let proposed filename have the value of the download attribute of the element of the
hyperlink that initiated the download at the time the download was
initiated.
If trusted operation is true, let filename have the value of proposed filename, and jump to the step labeled sanitize below.
If the resource has a `Content-Disposition`
header and that header specifies the attachment disposition type, let
filename have the value of proposed filename, and jump to the step labeled
sanitize below. [RFC6266]
No proposed filename: If trusted operation is true, or if the user indicated a preference for having the resource in question downloaded, let filename have a value derived from the URL of the resource in an implementation-defined manner, and jump to the step labeled sanitize below.
Let filename be set to the user's preferred filename or to a filename selected by the user agent, and jump to the step labeled sanitize below.
Sanitize: Optionally, allow the user to influence filename. For example, a user agent could prompt the user for a filename, potentially providing the value of filename as determined above as a default value.
Adjust filename to be suitable for the local file system.
If the platform conventions do not in any way use extensions to determine the types of file on the file system, then return filename as the filename.
Let claimed type be the type given by the resource's Content-Type metadata, if any is known. Let named type be the type given by filename's extension, if any is known. For the purposes of this step, a type is a mapping of a MIME type to an extension.
If named type is consistent with the user's preferences (e.g., because the value of filename was determined by prompting the user), then return filename as the filename.
If claimed type and named type are the same type (i.e., the type given by the resource's Content-Type metadata is consistent with the type given by filename's extension), then return filename as the filename.
If the claimed type is known, then alter filename to add an extension corresponding to claimed type.
Otherwise, if named type is known to be potentially dangerous (e.g. it
will be treated by the platform conventions as a native executable, shell script, HTML
application, or executable-macro-capable document) then optionally alter filename to add a known-safe extension
(e.g. ".txt").
Return filename as the filename.
User agents should ignore any directory or path information provided by the resource itself,
its URL, and any download attribute, in
deciding where to store the resulting file in the user's file system.
If a hyperlink created by an a or area element has a
ping attribute, and the user follows the hyperlink, and
the value of the element's href attribute can be parsed, relative to the element's node
document, without failure, then the user agent must take the ping attribute's value, split that string on ASCII whitespace, parse each resulting token, relative to the element's node document, and
then run these steps for each resulting URL ping URL, ignoring when
parsing returns failure:
If ping URL's scheme is not an HTTP(S) scheme, then return.
Optionally, return. (For example, the user agent might wish to ignore any or all ping URLs in accordance with the user's expressed preferences.)
Let settingsObject be the element's node document's relevant settings object.
Let request be a new request whose URL is ping URL, method is `POST`, header list is « (`Content-Type`,
`text/ping`) », body is `PING`, client is
settingsObject, destination is the
empty string, credentials mode is "include", referrer is "no-referrer", and whose use-URL-credentials flag is set, and whose
initiator type is "ping".
Let target URL be the result of encoding-parsing-and-serializing a
URL given the element's href attribute's value,
relative to the element's node document, and then:
Document object
containing the hyperlink being audited and ping URL have the same
originDocument containing the
hyperlink being audited is not "https"Ping-From` header with, as its value, the
URL of the document containing the hyperlink, and a
`Ping-To` HTTP header with, as its value, the target URL.Ping-To` HTTP header with, as its value,
target URL. Fetch request.
This may be done in parallel with the primary fetch, and is independent of the result of that fetch.
User agents should allow the user to adjust this behavior, for example in conjunction with a
setting that disables the sending of HTTP `Referer` (sic)
headers. Based on the user's preferences, UAs may either ignore the ping attribute altogether, or selectively ignore URLs in the
list (e.g. ignoring any third-party URLs); this is explicitly accounted for in the steps
above.
User agents must ignore any entity bodies returned in the responses. User agents may close the connection prematurely once they start receiving a response body.
When the ping attribute is present, user agents
should clearly indicate to the user that following the hyperlink will also cause secondary
requests to be sent in the background, possibly including listing the actual target URLs.
Ping-From` and `Ping-To` headersThe `Ping-From` and `Ping-To` HTTP request headers are included in hyperlink
auditing requests. Their value is a URL, serialized.
Support in all current engines.
The following table summarizes the link types that are defined by this specification, by their corresponding keywords. This table is non-normative; the actual definitions for the link types are given in the next few sections.
In this section, the term referenced document refers to the resource identified by the element representing the link, and the term current document refers to the resource within which the element representing the link finds itself.
To determine which link types apply to a link, a, area,
or form element, the element's rel attribute must be split on ASCII whitespace. The resulting tokens
are the keywords for the link types that apply to that element.
Except where otherwise specified, a keyword must not be specified more than once per rel attribute.
Some of the sections that follow the table below list synonyms for certain keywords. The
indicated synonyms are to be handled as specified by user agents, but must
not be used in documents (for example, the keyword "copyright").
Keywords are always ASCII case-insensitive, and must be compared as such.
New link types that are to be implemented by web browsers are to be added to this standard. The remainder can be registered as extensions.
| Link type | Effect on... | body-ok | Has `Link` processing | Brief description | ||
|---|---|---|---|---|---|---|
link | a and area | form | ||||
alternate | Hyperlink | not allowed | · | · | Gives alternate representations of the current document. | |
canonical | Hyperlink | not allowed | · | · | Gives the preferred URL for the current document. | |
author | Hyperlink | not allowed | · | · | Gives a link to the author of the current document or article. | |
bookmark | not allowed | Hyperlink | not allowed | · | · | Gives the permalink for the nearest ancestor section. |
dns-prefetch | External Resource | not allowed | Yes | · | Specifies that the user agent should preemptively perform DNS resolution for the target resource's origin. | |
expect | Internal Resource | not allowed | · | · | Expect an element with the target ID to appear in the current document. | |
external | not allowed | Annotation | · | · | Indicates that the referenced document is not part of the same site as the current document. | |
help | Hyperlink | · | · | Provides a link to context-sensitive help. | ||
icon | External Resource | not allowed | · | · | Imports an icon to represent the current document. | |
manifest | External Resource | not allowed | · | · | Imports or links to an application manifest. [MANIFEST] | |
modulepreload | External Resource | not allowed | Yes | · | Specifies that the user agent must preemptively fetch the module script and store it in the document's module map for later evaluation. Optionally, the module's dependencies can be fetched as well. | |
license | Hyperlink | · | · | Indicates that the main content of the current document is covered by the copyright license described by the referenced document. | ||
next | Hyperlink | · | · | Indicates that the current document is a part of a series, and that the next document in the series is the referenced document. | ||
nofollow | not allowed | Annotation | · | · | Indicates that the current document's original author or publisher does not endorse the referenced document. | |
noopener | not allowed | Annotation | · | · | Creates a top-level traversable with a non-auxiliary browsing
context if the hyperlink would otherwise create one that was auxiliary (i.e., has an
appropriate target attribute value). | |
noreferrer | not allowed | Annotation | · | · | No `Referer` (sic) header will be included.
Additionally, has the same effect as noopener. | |
opener | not allowed | Annotation | · | · | Creates an auxiliary browsing context if the hyperlink would otherwise create
a top-level traversable with a non-auxiliary browsing context (i.e.,
has "_blank" as target
attribute value). | |
pingback | External Resource | not allowed | Yes | · | Gives the address of the pingback server that handles pingbacks to the current document. | |
preconnect | External Resource | not allowed | Yes | Yes | Specifies that the user agent should preemptively connect to the target resource's origin. | |
prefetch | External Resource | not allowed | Yes | · | Specifies that the user agent should preemptively fetch and cache the target resource as it is likely to be required for a followup navigation. | |
preload | External Resource | not allowed | Yes | Yes | Specifies that the user agent must preemptively fetch and cache the target resource for current navigation according to the potential destination given by the as attribute (and the priority associated with the corresponding destination). | |
prev | Hyperlink | · | · | Indicates that the current document is a part of a series, and that the previous document in the series is the referenced document. | ||
privacy-policy | Hyperlink | not allowed | · | · | Gives a link to information about the data collection and usage practices that apply to the current document. | |
search | Hyperlink | · | · | Gives a link to a resource that can be used to search through the current document and its related pages. | ||
stylesheet | External Resource | not allowed | Yes | · | Imports a style sheet. | |
tag | not allowed | Hyperlink | not allowed | · | · | Gives a tag (identified by the given address) that applies to the current document. |
terms-of-service | Hyperlink | not allowed | · | · | Gives a link to information about the agreements between the current document's provider and users who wish to use the current document. | |
alternate"Support in one engine only.
The alternate keyword may be used with link,
a, and area elements.
The meaning of this keyword depends on the values of the other attributes.
link element and the rel
attribute also contains the keyword stylesheetThe alternate keyword modifies the meaning of the stylesheet keyword in the way described for that keyword. The
alternate keyword does not create a link of its own.
alternate keyword is used with the type attribute set to the value application/rss+xml or the value application/atom+xmlThe keyword creates a hyperlink referencing a syndication feed (though not necessarily syndicating exactly the same content as the current page).
For the purposes of feed autodiscovery, user agents should consider all link
elements in the document with the alternate keyword used and
with their type attribute set to the value application/rss+xml or the value application/atom+xml. If the user agent has the concept of a default
syndication feed, the first such element (in tree order) should be used as the
default.
The keyword creates a hyperlink referencing an alternate representation of the current document.
The nature of the referenced document is given by the hreflang, and type attributes.
If the alternate keyword is used with the hreflang attribute, and that attribute's value differs
from the document element's language, it indicates that the referenced
document is a translation.
If the alternate keyword is used with the type attribute, it indicates that the referenced document is
a reformulation of the current document in the specified format.
The hreflang and type attributes can be combined when specified with the alternate keyword.
This relationship is transitive — that is, if a document links to two other documents
with the link type "alternate", then, in addition to implying
that those documents are alternative representations of the first document, it is also implying
that those two documents are alternative representations of each other.
The author keyword may be used with link,
a, and area elements. This keyword creates a hyperlink.
For a and area elements, the author
keyword indicates that the referenced document provides further information about the author of
the nearest article element ancestor of the element defining the hyperlink, if there
is one, or of the page as a whole, otherwise.
For link elements, the author keyword indicates
that the referenced document provides further information about the author for the page as a
whole.
Synonyms: For historical reasons, user agents must also treat
link, a, and area elements that have a rev attribute with the value "made" as having the author keyword specified as a link relationship.
The bookmark keyword may be used with a and
area elements. This keyword creates a hyperlink.
The bookmark keyword gives a permalink for the nearest
ancestor article element of the linking element in question, or of the section the linking element is most closely associated with, if
there are no ancestor article elements.
The canonical keyword may be used with link
element. This keyword creates a hyperlink.
The canonical keyword indicates that URL given by the href attribute is the preferred URL for the current document. That
helps search engines reduce duplicate content, as described in more detail in The Canonical
Link Relation. [RFC6596]
dns-prefetch"The dns-prefetch keyword may be used with
link elements. This keyword creates an external
resource link. This keyword is body-ok.
The dns-prefetch keyword indicates that preemptively
performing DNS resolution for the origin of the specified resource is likely to be
beneficial, as it is highly likely that the user will require resources located at that
origin, and the user experience would be improved by preempting the latency costs
associated with DNS resolution.
There is no default type for resources given by the dns-prefetch keyword.
The appropriate times to fetch and process this type of link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
The fetch and process the linked resource steps for this type of linked resource,
given a link element el, are:
Let url be the result of encoding-parsing a URL given
el's href attribute's value, relative to
el's node document.
If url is failure, then return.
Let partitionKey be the result of determining the network partition key given el's node document's relevant settings object.
The user agent should resolve an origin given partitionKey and url's origin.
The expect keyword may be used with link
elements. This keyword creates an internal resource
link.
An internal resource link created by the expect
keyword can be used to block rendering until the element that
it indicates is connected to the document and fully
parsed.
There is no default type for resources given by the expect
keyword.
Whenever any of the following conditions occur for a link element
el:
the expect internal resource link is created
on el that is already browsing-context connected;
an expect internal resource link has been
created on el and el becomes
browsing-context connected;
an expectinternal resource link has been
created on el, el is already browsing-context connected, and
el's href attribute is set, changed, or removed;
or
an expect internal resource link has been
created on el, el is already browsing-context connected, and
el's media attribute is set, changed, or
removed,
then process el.
The following attribute change steps, given
element, localName, value, and namespace, are used to
ensure expect link elements respond to dynamic id and name changes:
If namespace is not null, then return.
If element is in a stack of open elements of an HTML parser, then return.
If any of the following is true:
then process internal resource links given element's node document.
The external keyword may be used with a,
area, and form elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The external keyword indicates that the link is leading to a
document that is not part of the site that the current document forms a part of.
The help keyword may be used with link,
a, area, and form elements. This keyword creates a
hyperlink.
For a, area, and form elements, the help keyword indicates that the referenced document provides further help
information for the parent of the element defining the hyperlink, and its children.
For link elements, the help keyword indicates that
the referenced document provides help for the page as a whole.
For a and area elements, on some browsers, the help keyword causes the link to use a different cursor.
icon"Support in all current engines.
The icon keyword may be used with link elements.
This keyword creates an external resource link.
The specified resource is an icon representing the page or site, and should be used by the user agent when representing the page in the user interface.
Icons could be auditory icons, visual icons, or other kinds of icons. If
multiple icons are provided, the user agent must select the most appropriate icon according to the
type, media, and sizes attributes. If there are multiple equally appropriate icons,
user agents must use the last one declared in tree order at the time that the user
agent collected the list of icons. If the user agent tries to use an icon but that icon is
determined, upon closer examination, to in fact be inappropriate (e.g. because it uses an
unsupported format), then the user agent must try the next-most-appropriate icon as determined by
the attributes.
There is no default type for resources given by the icon keyword.
However, for the purposes of determining the type of the
resource, user agents must expect the resource to be an image.
The sizes keywords represent icon sizes in raw pixels (as
opposed to CSS pixels).
To parse and process the attribute's value, the user agent must first split the attribute's value on ASCII whitespace, and must then parse each resulting keyword to determine what it represents.
Other keywords must be further parsed as follows to determine what they represent:
If the keyword doesn't contain exactly one U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character, then this keyword doesn't represent anything. Return for that keyword.
Let width string be the string before the "x" or
"X".
Let height string be the string after the "x" or
"X".
If either width string or height string start with a U+0030 DIGIT ZERO (0) character or contain any characters other than ASCII digits, then this keyword doesn't represent anything. Return for that keyword.
Apply the rules for parsing non-negative integers to width string to obtain width.
Apply the rules for parsing non-negative integers to height string to obtain height.
The keyword represents that the resource contains a bitmap icon with a width of width device pixels and a height of height device pixels.
The keywords specified on the sizes attribute must not
represent icon sizes that are not actually available in the linked resource.
The linked resource fetch setup steps for this type of linked resource, given a
link element el and request
request, are:
Set request's destination to
"image".
Return true.
The process a link header steps for this type of linked resource are to do nothing.
In the absence of a link with the icon keyword, for
Document objects whose URL's
scheme is an HTTP(S) scheme, user agents may
instead run these steps in parallel:
Let request be a new request whose
URL is the URL record obtained by
resolving the URL "/favicon.ico" against the
Document object's URL, client is the Document object's
relevant settings object, destination is "image",
synchronous flag is set, credentials
mode is "include", and whose use-URL-credentials flag
is set.
Let response be the result of fetching request.
Use response's unsafe response as an icon as if it had been
declared using the icon keyword.
For historical reasons, the icon keyword may be preceded by the
keyword "shortcut". If the "shortcut" keyword is
present, the rel attribute's entire value must be an
ASCII case-insensitive match for the string "shortcut icon" (with a single U+0020 SPACE character between the tokens and
no other ASCII whitespace).
The license keyword may be used with link,
a, area, and form elements. This keyword creates a
hyperlink.
The license keyword indicates that the referenced document
provides the copyright license terms under which the main content of the current document is
provided.
This specification does not specify how to distinguish between the main content of a document and content that is not deemed to be part of that main content. The distinction should be made clear to the user.
Synonyms: For historical reasons, user agents must also treat the keyword
"copyright" like the license keyword.
manifest"Support in one engine only.
The manifest keyword may be used with link elements.
This keyword creates an external resource link.
The manifest keyword indicates the manifest file that provides
metadata associated with the current document.
There is no default type for resources given by the manifest
keyword.
When a web application is not installed, the appropriate time to fetch and process the linked resource for this link type is when the user agent deems it necessary. For example, when the user chooses to install the web application.
For an installed web application, the appropriate times to fetch and process the linked resource for this link type are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
In any case, only the first link element in tree order whose rel attribute contains the token manifest may be used.
A user agent must not delay the load event for this link type.
The linked resource fetch setup steps for this type of linked resource, given a
link element el and request
request, are:
Let navigable be el's node document's node navigable.
If navigable is null, then return false.
If navigable is not a top-level traversable, then return false.
Set request's initiator to
"manifest".
Set request's destination to
"manifest".
Set request's mode to "cors".
Set request's credentials
mode to the CORS settings attribute credentials mode for el's
crossorigin content attribute.
Return true.
To process this type of linked resource given
a link element el, boolean success, response response, and byte sequence
bodyBytes:
If response's Content-Type metadata is not a JSON MIME type, then set success to false.
If success is true:
Let document URL be el's node document's URL.
Let manifest URL be response's URL.
Process the manifest given document URL, manifest URL, and bodyBytes. [MANIFEST]
The process a link header steps for this type of linked resource are to do nothing.
modulepreload"The modulepreload keyword may be used with
link elements. This keyword creates an external resource link. This
keyword is body-ok.
The modulepreload keyword is a specialized alternative
to the preload keyword, with a processing model geared toward
preloading module scripts. In particular, it uses the specific
fetch behavior for module scripts (including, e.g., a different interpretation of the crossorigin attribute), and places the result into the
appropriate module map for later evaluation. In
contrast, a similar external resource link using the preload keyword would place the result in the preload cache, without
affecting the document's module map.
Additionally, implementations can take advantage of the fact that module scripts declare their dependencies in order to fetch the specified module's
dependency as well. This is intended as an optimization opportunity, since the user agent knows
that, in all likelihood, those dependencies will also be needed later. It will not generally be
observable without using technology such as service workers, or monitoring on the server side.
Notably, the appropriate load or error events will occur after the specified module is fetched, and
will not wait for any dependencies.
A user agent must not delay the load event for this link type.
The appropriate times to fetch and process the linked resource for such a link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
The fetch and process the linked resource algorithm for modulepreload links, given a link element
el, is as follows:
If el's href attribute's value is the
empty string, then return.
Let destination be the current state of el's as attribute (a destination), or "script" if
it is in no state.
If destination is not script-like, then queue an element
task on the networking task source given el to fire an event named error
at el, and return.
Let url be the result of encoding-parsing a URL given
el's href attribute's value, relative to
el's node document.
If url is failure, then return.
Let settings object be el's node document's relevant settings object.
Let credentials mode be the CORS settings attribute credentials
mode for el's crossorigin
attribute.
Let cryptographic nonce be el.[[CryptographicNonce]].
Let integrity metadata be the value of el's integrity attribute, if it is specified, or the empty string
otherwise.
If el does not have an integrity
attribute, then set integrity metadata to the result of resolving a module
integrity metadata with url and settings object.
Let referrer policy be the current state of el's referrerpolicy attribute.
Let fetch priority be the current state of el's fetchpriority attribute.
Let options be a script fetch options whose cryptographic nonce is cryptographic
nonce, integrity metadata is
integrity metadata, parser
metadata is "not-parser-inserted", credentials mode is credentials
mode, referrer
policy is referrer policy, and fetch priority is
fetch priority.
Fetch a modulepreload module script graph given url, destination, settings object, options, and with the following steps given result:
If result is null, then fire an
event named error at el,
and return.
Fire an event named load at el.
The process a link header steps for this type of linked resource are to do nothing.
The nofollow keyword may be used with a,
area, and form elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The nofollow keyword indicates that the link is not endorsed
by the original author or publisher of the page, or that the link to the referenced document was
included primarily because of a commercial relationship between people affiliated with the two
pages.
noopener"Support in all current engines.
Support in all current engines.
The noopener keyword may be used with a,
area, and form elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The keyword indicates that any newly created top-level traversable which results
from following the hyperlink will not contain an auxiliary browsing
context. E.g., the resulting Window's opener
getter will return null.
noreferrer"Support in all current engines.
Support in all current engines.
The noreferrer keyword may be used with a,
area, and form elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
It indicates that no referrer information is to be leaked when following the link and also
implies the noopener keyword behavior under the same
conditions.
The opener keyword may be used with a,
area, and form elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The keyword indicates that any newly created top-level traversable which results from following the hyperlink will contain an auxiliary browsing context.
The pingback keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
For the semantics of the pingback keyword, see
Pingback 1.0. [PINGBACK]
preconnect"Support in all current engines.
The preconnect keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
The preconnect keyword indicates that preemptively
initiating a connection to the origin of the specified resource is likely to be
beneficial, as it is highly likely that the user will require resources located at that
origin, and the user experience would be improved by preempting the latency costs
associated with establishing the connection.
There is no default type for resources given by the preconnect keyword.
A user agent must not delay the load event for this link type.
The appropriate times to fetch and process this type of link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the crossorigin attribute of the
link element of an external resource
link that is already browsing-context connected is set, changed, or
removed.
The fetch and process the linked resource steps for this type of linked resource,
given a link element el, are to create link options from el and
to preconnect given the result.
The process a link header step for this type of linked resource given a link processing options options are to preconnect given options.
prefetch"The prefetch keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
The prefetch keyword indicates that preemptively fetching and caching the specified resource or same-site document is
likely to be beneficial, as it is highly likely that the user will require this resource for
future navigations.
There is no default type for resources given by the prefetch
keyword.
The appropriate times to fetch and process this type of link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the crossorigin attribute of the
link element of an external resource
link that is already browsing-context connected is set, changed, or
removed.
The fetch and process the linked resource algorithm for prefetch links, given a link element
el, is as follows:
If el's href attribute's value is the
empty string, then return.
Let options be the result of creating link options from el.
Set options's destination to the empty string.
Let request be the result of creating a link request given options.
If request is null, then return.
Set request's initiator to
"prefetch".
Let processPrefetchResponse be the following steps given a response response and null, failure, or a byte sequence bytesOrNull:
If response is a network error, fire an event named error at el.
Otherwise, fire an event named load at el.
The user agent should fetch request, with processResponseConsumeBody set to processPrefetchResponse. User agents may delay the fetching of request to prioritize other requests that are necessary for the current document.
The process a link header steps for this type of linked resource are to do nothing.
preload"Support in one engine only.
The preload keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
The preload keyword indicates that the user agent will
preemptively fetch and cache the specified resource according
to the potential destination given by the
as attribute, and the priority given by the fetchpriority attribute, as it is highly likely that the
user will require this resource for the current navigation.
There is no default type for resources given by the preload
keyword.
A user agent must not delay the load event for this link type.
The appropriate times to fetch and process the linked resource for such a link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the as attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the type attribute of the link
element of an external resource link that is already browsing-context
connected, but was previously not obtained due to the type attribute specifying an unsupported type for the request
destination, is set, removed, or
changed.
When the media attribute of the link
element of an external resource link that is already browsing-context
connected, but was previously not obtained due to the media attribute not
matching the environment, is changed or
removed.
The fetch and process the linked resource steps for this type of linked resource,
given a link element el, are:
Update the source set for el.
Let options be the result of creating link options from el.
Preload options, with the following steps given a response response:
If response is a network error, fire an event named error at el. Otherwise, fire an event named
load at el.
The process a link header step for this type of link given a link processing options options is to preload options.
The privacy-policy keyword may be used with
link, a, and area elements. This keyword creates a
hyperlink.
The privacy-policy keyword indicates that the
referenced document contains information about the data collection and usage practices that apply
to the current document, as described in more detail in Additional Link Relation
Types. The referenced document may be a standalone privacy policy, or a specific section of
some more general document. [RFC6903]
The search keyword may be used with link,
a, area, and form elements. This keyword creates a
hyperlink.
The search keyword indicates that the referenced document
provides an interface specifically for searching the document and its related resources.
The stylesheet keyword may be used with link
elements. This keyword creates an external resource
link that contributes to the styling processing model. This keyword is
body-ok.
The specified resource is a CSS style sheet that describes how to present the document.
Support in one engine only.
The default type for resources given by the stylesheet
keyword is text/css.
A link element of this type is implicitly potentially render-blocking
if the element was created by its node document's parser.
When the disabled attribute of a link
element with a stylesheet keyword is set, disable the associated CSS style sheet.
The appropriate times to fetch and process this type of link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the disabled attribute of the
link element of an external resource link that is already
browsing-context connected is set, changed, or removed.
When the crossorigin attribute of the
link element of an external resource
link that is already browsing-context connected is set, changed, or
removed.
When the type attribute of the link
element of an external resource link that is already browsing-context
connected is set or changed to a value that does not or no longer matches the Content-Type metadata of the previous obtained external resource, if
any.
When the type attribute of the link
element of an external resource link that is already browsing-context
connected, but was previously not obtained due to the type attribute specifying an unsupported type, is removed or
changed.
When the external resource link that is already browsing-context connected changes from being an alternative style sheet to not being one, or vice versa.
Quirk: If the document has been set to quirks mode, has the
same origin as the URL of the external resource,
and the Content-Type metadata of the external resource is not a
supported style sheet type, the user agent must instead assume it to be text/css.
The linked resource fetch setup steps for this type of linked resource, given a
link element el and request
request, are:
If el's disabled attribute is set,
then return false.
If el contributes a script-blocking style sheet, append el to its node document's script-blocking style sheet set.
If el's media attribute's value
matches the environment and el is
potentially render-blocking, then block rendering on
el.
If el is currently render-blocking, then set request's render-blocking to true.
Return true.
To process this type of linked resource
given a link element el, boolean success, response response, and byte sequence
bodyBytes:
If the resource's Content-Type metadata is not
text/css, then set success to false.
If el no longer creates an external resource link that contributes to the styling processing model, or if, since the resource in question was fetched, it has become appropriate to fetch it again, then:
Remove el from el's node document's script-blocking style sheet set.
Return.
If el has an associated CSS style sheet, remove the CSS style sheet.
If success is true, then:
Create a CSS style sheet with the following properties:
response's URL list[0]
el
The media attribute of el.
The title attribute of el, if
el is in a document tree, or the empty string otherwise.
Set if the link is an alternative style sheet and el's explicitly enabled is false; unset otherwise.
Set if the resource is CORS-same-origin; unset otherwise.
null
Left at its default value.
Left uninitialized.
The CSS environment encoding is the result of running the following steps: [CSSSYNTAX]
If el has a charset attribute,
get an encoding from that attribute's value. If
that succeeds, return the resulting encoding. [ENCODING]
Otherwise, return the document's character encoding. [DOM]
Fire an event named load at el.
Otherwise, fire an event named error at el.
If el contributes a script-blocking style sheet, then:
Assert: el's node document's script-blocking style sheet set contains el.
Remove el from its node document's script-blocking style sheet set.
Unblock rendering on el.
The process a link header steps for this type of linked resource are to do nothing.
The tag keyword may be used with a and
area elements. This keyword creates a hyperlink.
The tag keyword indicates that the tag that the
referenced document represents applies to the current document.
The terms-of-service keyword may be used with
link, a, and area elements. This keyword creates a
hyperlink.
The terms-of-service keyword indicates that the
referenced document contains information about the agreements between the current document's
provider and users who wish to use the current document, as described in more detail in
Additional Link Relation Types. [RFC6903]
Some documents form part of a sequence of documents.
A sequence of documents is one where each document can have a previous sibling and a next sibling. A document with no previous sibling is the start of its sequence, a document with no next sibling is the end of its sequence.
A document may be part of multiple sequences.
The next keyword may be used with link,
a, area, and form elements. This keyword creates a
hyperlink.
The next keyword indicates that the document is part of a
sequence, and that the link is leading to the document that is the next logical document in the
sequence.
When the next keyword is used with a link
element, user agents should process such links as if they were using one of the dns-prefetch, preconnect, or
prefetch keywords. Which keyword the user agent wishes to use
is implementation-dependent; for example, a user agent may wish to use the less-costly preconnect processing model when trying to conserve data, battery
power, or processing power, or may wish to pick a keyword depending on heuristic analysis of past
user behavior in similar scenarios.
The prev keyword may be used with link,
a, area, and form elements. This keyword creates a
hyperlink.
The prev keyword indicates that the document is part of a
sequence, and that the link is leading to the document that is the previous logical document in
the sequence.
Synonyms: For historical reasons, user agents must also treat the keyword
"previous" like the prev keyword.
Anyone is free to edit the microformats page for existing rel values at any time to add a type. Extension types must be specified with the following information:
The actual value being defined. The value should not be confusingly similar to any other defined value (e.g. differing only in case).
If the value contains a U+003A COLON character (:), it must also be an absolute URL.
linkOne of the following:
link elements.link element; it creates a
hyperlink.link element; it creates an external
resource link.a and areaOne of the following:
a and area elements.a and area elements; it creates a
hyperlink.a and area elements; it creates
an external resource link.a and area elements; it annotates other hyperlinks
created by the element.formOne of the following:
form elements.form elements; it creates a
hyperlink.form elements; it creates an external
resource link.form elements; it annotates other hyperlinks created by the
element.A short non-normative description of what the keyword's meaning is.
A link to a more detailed description of the keyword's semantics and requirements. It could be another page on the wiki, or a link to an external page.
A list of other keyword values that have exactly the same processing requirements. Authors should not use the values defined to be synonyms, they are only intended to allow user agents to support legacy content. Anyone may remove synonyms that are not used in practice; only names that need to be processed as synonyms for compatibility with legacy content are to be registered in this way.
One of the following:
If a keyword is found to be redundant with existing values, it should be removed and listed as a synonym for the existing value.
If a keyword is registered in the "proposed" state for a period of a month or more without being used or specified, then it may be removed from the registry.
If a keyword is added with the "proposed" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value. If a keyword is added with the "proposed" status and found to be harmful, then it should be changed to "discontinued" status.
Anyone can change the status at any time, but should only do so in accordance with the definitions above.
Conformance checkers must use the information given on the microformats page for existing rel values to establish if a value is allowed or not: values defined in this specification or marked as "proposed" or "ratified" must be accepted when used on the elements for which they apply as described in the "Effect on..." field, whereas values marked as "discontinued" or not listed in either this specification or on the aforementioned page must be rejected as invalid. Conformance checkers may cache this information (e.g. for performance reasons or to avoid the use of unreliable network connectivity).
When an author uses a new type not defined by either this specification or the wiki page, conformance checkers should offer to add the value to the wiki, with the details described above, with the "proposed" status.
Types defined as extensions in the microformats
page for existing rel values with the status "proposed" or "ratified" may be used with the
rel attribute on link, a, and area
elements in accordance to the "Effect on..." field. [MFREL]
The ins and del elements represent edits to the document.
ins elementSupport in all current engines.
cite — Link to the source of the quotation or more information about the edit
datetime — Date and (optionally) time of the change
HTMLModElement.The ins element represents an addition to the document.
ins elements should not cross implied paragraph
boundaries.
del elementSupport in all current engines.
cite — Link to the source of the quotation or more information about the edit
datetime — Date and (optionally) time of the change
HTMLModElement.The del element represents a removal from the document.
del elements should not cross implied paragraph
boundaries.
ins and del elementsIf the cite attribute is present, it must be a valid
URL potentially surrounded by spaces that explains the change. To obtain
the corresponding citation link, the value of the attribute must be parsed relative to the element's node document. User agents may
allow users to follow such citation links, but they are primarily intended for private use (e.g.,
by server-side scripts collecting statistics about a site's edits), not for readers.
If present, the datetime attribute's value must be a
valid date string with optional time.
User agents must parse the datetime attribute according
to the parse a date or time string algorithm. If that doesn't return a date or a global date and time,
then the modification has no associated timestamp (the value is non-conforming; it is not a
valid date string with optional time). Otherwise, the modification is marked as
having been made at the given date or global date and time. If the given value is a global date and time then user agents should use the associated
time-zone offset information to determine which time zone to present the given datetime in.
This value may be shown to the user, but it is primarily intended for private use.
The ins and del elements must implement the
HTMLModElement interface:
Support in all current engines.
The cite IDL
attribute must reflect the element's cite content
attribute. The dateTime IDL attribute must reflect the
element's datetime content attribute.
This section is non-normative.
Since the ins and del elements do not affect paragraphing, it is possible, in some cases where paragraphs are implied (without explicit p elements), for an
ins or del element to span both an entire paragraph or other
non-phrasing content elements and part of another paragraph. For example:
By only wrapping some paragraphs in p elements, one can even get the end of one
paragraph, a whole second paragraph, and the start of a third paragraph to be covered by the same
ins or del element (though this is very confusing, and not considered
good practice):
However, due to the way implied paragraphs are defined, it is
not possible to mark up the end of one paragraph and the start of the very next one using the same
ins or del element. You instead have to use one (or two) p
element(s) and two ins or del elements, as for example:
Partly because of the confusion described above, authors are strongly encouraged to always mark
up all paragraphs with the p element, instead of having ins or
del elements that cross implied paragraphs
boundaries.
This section is non-normative.
The content models of the ol and ul elements do not allow
ins and del elements as children. Lists always represent all their
items, including items that would otherwise have been marked as deleted.
To indicate that an item is inserted or deleted, an ins or del
element can be wrapped around the contents of the li element. To indicate that an
item has been replaced by another, a single li element can have one or more
del elements followed by one or more ins elements.
This section is non-normative.
The elements that form part of the table model have complicated content model requirements that
do not allow for the ins and del elements, so indicating edits to a
table can be difficult.
To indicate that an entire row or an entire column has been added or removed, the entire
contents of each cell in that row or column can be wrapped in ins or del
elements (respectively).
Generally speaking, there is no good way to indicate more complicated edits (e.g. that a cell was removed, moving all subsequent cells up or to the left).
picture elementSupport in all current engines.
Support in all current engines.
source elements, followed by one img element,
optionally intermixed with script-supporting elements.The picture element is a container
which provides multiple sources to its contained img element
to allow authors to declaratively control or give hints to the user agent about which image resource to use,
based on the screen pixel density, viewport size, image format, and other factors.
It represents its children.
source elementSupport in all current engines.
Support in all current engines.
picture element, before the img element.track elements.type — Type of embedded resource
media — Applicable media
src (in audio or video) — Address of the resource
srcset (in picture) — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.
sizes (in picture) — Image sizes for different page layouts
width (in picture) — Horizontal dimension
height (in picture) — Vertical dimension
The source element allows authors to specify multiple alternative
source sets for img elements or multiple alternative
media resources for media
elements. It does not represent anything on its own.
The remainder of the requirements depend on whether the parent is a picture
element or a media element:
source element's parent is a picture elementThe srcset attribute contributes the image sources to the source set, if the
source element is selected.
The source element supports dimension attributes. The
img element can use the width and height attributes of a source element, instead of
those on the img element itself, to determine its rendered dimensions and
aspect-ratio, as defined in the Rendering section.
The type attribute gives the type of the images in the
source set, to allow the user agent to skip to the next source element
if it does not support the given type.
When a source element has a following sibling source element or
img element with a srcset attribute
specified, it must have at least one of the following:
A media attribute specified with a value that,
after stripping leading and trailing
ASCII whitespace, is not the empty string and is not an ASCII
case-insensitive match for the string "all".
A type attribute specified.
The src attribute must not be present.
source element's parent is a media elementThe type attribute gives the type of the media
resource, to help the user agent determine if it can play this media
resource before fetching it. The codecs parameter, which certain
MIME types define, might be necessary to specify exactly how the resource is encoded.
[RFC6381]
The source HTML element insertion
steps, given insertedNode, are:
If insertedNode's parent is a media element that has no src attribute and whose networkState has the value NETWORK_EMPTY, then invoke that media
element's resource selection
algorithm.
If insertedNode's next sibling is an img element and its parent is
a picture element, then, count this as a relevant
mutation for the img element.
The source HTML element removing
steps, given removedNode and oldParent, are:
If removedNode's next sibling was an img element and
oldParent is a picture element, then, count this as a relevant mutation for the img element.
The IDL attributes src, type, srcset, sizes, and media must reflect the respective
content attributes of the same name.
img elementSupport in all current engines.
Support in all current engines.
usemap attribute: Interactive content.picture element, after all source elements.alt — Replacement text for use when images are not available
src — Address of the resource
srcset — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.
sizes — Image sizes for different page layouts
crossorigin — How the element handles crossorigin requests
usemap — Name of image map to use
ismap — Whether the image is a server-side image map
width — Horizontal dimension
height — Vertical dimension
referrerpolicy — Referrer policy for fetches initiated by the element
decoding — Decoding hint to use when processing this image for presentation
loading — Used when determining loading deferral
fetchpriority — Sets the priority for fetches initiated by the element
alt attribute: for authors; for implementers.An img element represents an image.
An img element has a dimension
attribute source, initially set to the element itself.
Support in all current engines.
Support in all current engines.
The image given by the src
and srcset attributes, and
any previous sibling source elements' srcset
attributes if the parent is a picture element, is the embedded content; the value of
the alt attribute provides
equivalent content for those who cannot process images or who have image loading disabled (i.e. it
is the img element's fallback content).
The requirements on the alt attribute's value are described
in a separate section.
The src attribute must be present, and must contain a
valid non-empty URL potentially surrounded by spaces referencing a non-interactive,
optionally animated, image resource that is neither paged nor scripted.
The srcset attribute may also be present, and is a
srcset attribute.
The srcset attribute and the src attribute (if width
descriptors are not used) contribute the image sources
to the source set (if no source element was selected).
Support in all current engines.
The decoding
attribute indicates the preferred method to decode this
image. The attribute, if present, must be an image decoding hint. This attribute's missing value default and invalid value default are both the auto state.
HTMLImageElement/fetchPriority
When the loading attribute's state is changed to the
Eager state, the user agent must run these
steps:
Let resumptionSteps be the img element's lazy load
resumption steps.
If resumptionSteps is null, then return.
Set the img's lazy load resumption steps to null.
Invoke resumptionSteps.
The img HTML element insertion
steps, given insertedNode, are:
If insertedNode's parent is a picture element, then, count this as
a relevant mutation for
insertedNode.
The img HTML element removing
steps, given removedNode and oldParent, are:
If oldParent is a picture element, then, count this as a
relevant mutation for removedNode.
The img element must not be used as a layout tool. In particular, img
elements should not be used to display transparent images, as such images rarely convey meaning and
rarely add anything useful to the document.
What an img element represents depends on the src attribute and the alt
attribute.
src attribute is set and the alt attribute is set to the empty stringThe image is either decorative or supplemental to the rest of the content, redundant with some other information in the document.
If the image is available and the user agent is configured to display that image, then the element represents the element's image data.
Otherwise, the element represents nothing, and may be omitted completely from the rendering. User agents may provide the user with a notification that an image is present but has been omitted from the rendering.
src attribute is set and the alt attribute is set to a value that isn't emptyThe image is a key part of the content; the alt attribute
gives a textual equivalent or replacement for the image.
If the image is available and the user agent is configured to display that image, then the element represents the element's image data.
Otherwise, the element represents the text given by the alt attribute. User agents may provide the user with a notification
that an image is present but has been omitted from the rendering.
src attribute is set and the alt attribute is notThe image might be a key part of the content, and there is no textual equivalent of the image available.
If the image is available and the user agent is configured to display that image, then the element represents the element's image data.
If the image has a src attribute whose value is
the empty string, then the element represents nothing.
Otherwise, the user agent should display some sort of indicator that there is an image that is not being rendered, and may, if requested by the user, or if so configured, or when required to provide contextual information in response to navigation, provide caption information for the image, derived as follows:
If the image has a title attribute whose value is not
the empty string, then return the value of that attribute.
If the image is a descendant of a figure element that has a child
figcaption element, and, ignoring the figcaption element and its
descendants, the figure element has no flow content descendants other
than inter-element whitespace and the img element, then return the
contents of the first such figcaption element.
Return nothing. (There is no caption information.)
src attribute is not set and either the alt attribute is set to the empty string or the alt attribute is not set at allThe element represents nothing.
The element represents the text given by the alt attribute.
The alt attribute does not represent advisory information.
User agents must not present the contents of the alt attribute
in the same way as content of the title attribute.
User agents may always provide the user with the option to display any image, or to prevent any image from being displayed. User agents may also apply heuristics to help the user make use of the image when the user is unable to see it, e.g. due to a visual disability or because they are using a text terminal with no graphics capabilities. Such heuristics could include, for instance, optical character recognition (OCR) of text found within the image.
The contents of img elements, if any, are ignored for the purposes of
rendering.
The usemap attribute,
if present, can indicate that the image has an associated
image map.
The ismap attribute is a
boolean attribute. The attribute must not be specified
on an element that does not have an ancestor a element
with an href attribute.
The img element supports dimension
attributes.
Support in all current engines.
Support in all current engines.
Support in all current engines.
The alt, src, srcset, and sizes IDL attributes must
reflect the respective content attributes of the same name.
Support in all current engines.
The crossOrigin IDL attribute must
reflect the crossorigin content attribute,
limited to only known values.
Support in all current engines.
The useMap IDL
attribute must reflect the usemap content
attribute.
Support in all current engines.
The isMap IDL
attribute must reflect the ismap content
attribute.
HTMLImageElement/referrerPolicy
Support in all current engines.
The referrerPolicy IDL attribute must
reflect the referrerpolicy content
attribute, limited to only known values.
Support in all current engines.
The decoding
IDL attribute must reflect the decoding
content attribute, limited to only known values.
Support in all current engines.
On setting, they must act as if they reflected the respective content attributes of the same name.
This section is non-normative.
To embed an image in HTML, when there is only a single image resource, use the img
element and its src attribute.
However, there are a number of situations for which the author might wish to use multiple image resources that the user agent can choose from:
Different users might have different environmental characteristics:
The users' physical screen size might be different from one another.
The users' screen pixel density might be different from one another.
The users' zoom level might be different from one another, or might change for a single user over time.
The users' screen orientation might be different from one another, or might change for a single user over time.
The users' network speed, network latency and bandwidth cost might be different from one another, or might change for a single user over time.
The above situations are not mutually exclusive. For example, it is reasonable to combine different resources for different device-pixel-ratio with different resources for art direction.
While it is possible to solve these problems using scripting, doing so introduces some other problems:
Some user agents aggressively download images specified in the HTML markup, before scripts have had a chance to run, so that web pages complete loading sooner. If a script changes which image to download, the user agent will potentially start two separate downloads, which can instead cause worse page loading performance.
If the author avoids specifying any image in the HTML markup and instead instantiates a single download from script, that avoids the double download problem above but then no image will be downloaded at all for users with scripting disabled and the aggressive image downloading optimization will also be disabled.
With this in mind, this specification introduces a number of features to address the above problems in a declarative manner.
The src and srcset
attributes on the img element can be used, using the x
descriptor, to provide multiple images that only vary in their size (the smaller image is a
scaled-down version of the bigger image).
The srcset and sizes attributes can be used, using the w
descriptor, to provide multiple images that only vary in their size (the smaller image is a
scaled-down version of the bigger image).
The picture element and the source element, together with the media attribute, can be used to provide multiple images that
vary the image content (for instance the smaller image might be a cropped version of the bigger
image).
The type attribute on the source element
can be used to provide multiple images in different formats.
This section is non-normative.
CSS and media queries can be used to construct graphical page layouts that adapt dynamically to
the user's environment, in particular to different viewport dimensions and pixel
densities. For content, however, CSS does not help; instead, we have the img element's
srcset attribute and the picture element.
This section walks through a sample case showing how to use these features.
Consider a situation where on wide screens (wider than 600 CSS
pixels) a 300×150 image named a-rectangle.png is to be used,
but on smaller screens (600 CSS pixels and less), a smaller
100×100 image called a-square.png is to be used. The markup for this
would look like this:
The problem with this is that the user agent does not necessarily know what dimensions to use for the image when the image is loading. To avoid the layout having to be reflowed multiple times as the page is loading, CSS and CSS media queries can be used to provide the dimensions:
Alternatively, the width and height attributes can be used to provide the width and height for
legacy user agents, using CSS just for the user agents that support picture:
The img element is used with the src attribute,
which gives the URL of the image to use for legacy user agents that do not support the
picture element. This leads to a question of which image to provide in the src attribute.
If the author wants the biggest image in legacy user agents, the markup could be as follows:
However, if legacy mobile user agents are more important, one can list all three images in the
source elements, overriding the src attribute
entirely.
Since at this point the src attribute is actually being
ignored entirely by picture-supporting user agents, the src attribute can default to any image, including one that is neither
the smallest nor biggest:
Above the max-width media feature is used, giving the maximum
(viewport) dimensions that an image is intended for. It is also possible to use min-width instead.
source,
img, and link elementsIf present, its value must consist of one or more image candidate strings, each separated from the next by a U+002C COMMA character (,). If an image candidate string contains no descriptors and no ASCII whitespace after the URL, the following image candidate string, if there is one, must begin with one or more ASCII whitespace.
There must not be an image candidate string for an element that has the same width descriptor value as another image candidate string's width descriptor value for the same element.
There must not be an image candidate string for an element that has the same
pixel density descriptor value as another image candidate string's
pixel density descriptor value for the same element. For the purpose of this
requirement, an image candidate string with no descriptors is equivalent to an
image candidate string with a 1x descriptor.
If an image candidate string for an element has the width descriptor specified, all other image candidate strings for that element must also have the width descriptor specified.
The specified width in an image candidate string's width descriptor must match the natural width in the resource given by the image candidate string's URL, if it has a natural width.
If an element has a sizes attribute present, all image candidate strings for that element must have the width descriptor specified.
If present, the value must be a valid source size list.
A valid source size list is a string that matches the following grammar: [CSSVALUES] [MQ]
A <source-size-value> that is a <length> must not be negative, and must not use CSS functions other than the math functions.
The auto keyword may be specified in the sizes attribute of source elements and sizes attribute of img elements, if the following
conditions are met. Otherwise, auto must not be
specified.
The element is a source element with a following sibling
img element.
The element is an img element.
The img element referenced in either condition above allows
auto-sizes.
The <source-size-value> gives the intended layout width of the image. The author can specify different widths for different environments with <media-condition>s.
An img element has a current request and a pending request.
The current request is initially set to a new image request.
The pending request is initially set to null.
An image request has a state, current URL, and image data.
An image request's state is one of the following:
An image request's current URL is initially the empty string.
An image request's image data is the decoded image data.
An image request's state is initially unavailable.
When an img element's current request is available, the img element provides a paint
source whose width is the image's density-corrected natural width (if any), whose height is the image's density-corrected natural height
(if any), and whose appearance is the natural appearance of the image.
An img element is said to use srcset or
picture if it has a srcset attribute
specified or if it has a parent that is a picture element.
All img and link elements are associated with a source set.
A source size is a <source-size-value>.
When a source size has a unit relative to the viewport,
it must be interpreted relative to the img element's node document's
viewport. Other units must be interpreted the same as in Media Queries.
[MQ]
A parse error for algorithms in this section indicates a non-fatal mismatch between input and requirements. User agents are encouraged to expose parse errors somehow.
Whether the image is fetched successfully or not (e.g. whether the response status was an ok status) must be ignored when determining the image's type and whether it is a valid image.
The user agent should apply the image sniffing rules to determine the type of the image, with the image's associated Content-Type headers giving the official type. If these rules are not applied, then the type of the image must be the type given by the image's associated Content-Type headers.
User agents must not support non-image resources with the img element (e.g. XML
files whose document element is an HTML element). User agents must not run executable
code (e.g. scripts) embedded in the image resource. User agents must only display the first page
of a multipage resource (e.g. a PDF file). User agents must not allow the resource to act in an
interactive fashion, but should honour any animation in the resource.
This specification does not specify which image types are to be supported.
By default, images are obtained immediately. User agents may provide users with the option to instead obtain them on-demand. (The on-demand option might be used by bandwidth-constrained users, for example.)
When obtaining images immediately, the user agent must synchronously update the image
data of the img element, with the restart animation flag set if so
stated, whenever that element is created or has experienced relevant mutations.
When obtaining images on demand, the user agent must update the image data of an
img element whenever it needs the image data (i.e., on demand), but only if the
img element's current request's state is unavailable. When an
img element has experienced relevant mutations, if the user agent only
obtains images on demand, the img element's current request's state must return to unavailable.
Each Document object must have a list of available images. Each image
in this list is identified by a tuple consisting of an absolute URL, a CORS
settings attribute mode, and, if the mode is not No
CORS, an origin.
Each image furthermore has an ignore higher-layer caching flag.
User agents may copy entries from one Document
object's list of available images to another at any time (e.g. when the
Document is created, user agents can add to it all the images that are loaded in
other Documents), but must not change the keys of entries copied in this way when
doing so, and must unset the ignore higher-layer caching flag for the copied entry.
User agents may also remove images from such lists at any time (e.g. to save
memory).
User agents must remove entries in the list of available images as appropriate
given higher-layer caching semantics for the resource (e.g. the HTTP `Cache-Control` response header) when the ignore
higher-layer caching flag is unset.
Image decoding is said to be synchronous if it prevents presentation of other content until it is finished. Typically, this has an effect of atomically presenting the image and any other content at the same time. However, this presentation is delayed by the amount of time it takes to perform the decode.
Image decoding is said to be asynchronous if it does not prevent presentation of other content. This has an effect of presenting non-image content faster. However, the image content is missing on screen until the decode finishes. Once the decode is finished, the screen is updated with the image.
In both synchronous and asynchronous decoding modes, the final content is presented to screen after the same amount of time has elapsed. The main difference is whether the user agent presents non-image content ahead of presenting the final content.
In order to aid the user agent in deciding whether to perform synchronous or asynchronous
decode, the decoding attribute can be set on
img elements. The possible values of the decoding attribute are the following image decoding
hint keywords:
| Keyword | State | Description |
|---|---|---|
sync
| Sync | Indicates a preference to decode this image synchronously for atomic presentation with other content. |
async
| Async | Indicates a preference to decode this image asynchronously to avoid delaying presentation of other content. |
auto
| Auto | Indicates no preference in decoding mode (the default). |
When decoding an image, the user agent should
respect the preference indicated by the decoding
attribute's state. If the state indicated is auto, then the user agent is free to choose any
decoding behavior.
While a user agent is running the above algorithm for an element x, there must be a strong reference from the element's node document to the element x, even if that element is not connected.
An image source can have a pixel density descriptor, a width descriptor, or no descriptor at all accompanying its URL. Normalizing a source set gives every image source a pixel density descriptor.
Except where otherwise specified, the alt attribute must be
specified and its value must not be empty; the value must be an appropriate replacement for the
image. The specific requirements for the alt attribute depend on
what the image is intended to represent, as described in the following sections.
The most general rule to consider when writing alternative text is the following: the
intent is that replacing every image with the text of its alt
attribute does not change the meaning of the page.
So, in general, alternative text can be written by considering what one would have written had one not been able to include the image.
A corollary to this is that the alt attribute's value should
never contain text that could be considered the image's caption, title, or
legend. It is supposed to contain replacement text that could be used by users
instead of the image; it is not meant to supplement the image. The title attribute can be used for supplemental information.
Another corollary is that the alt attribute's value should
not repeat information that is already provided in the prose next to the image.
When an a element that creates a hyperlink, or a button
element, has no textual content but contains one or more images, the alt attributes must contain text that together convey the purpose of
the link or button.
Sometimes something can be more clearly stated in graphical form, for example as a flowchart, a
diagram, a graph, or a simple map showing directions. In such cases, an image can be given using
the img element, but the lesser textual version must still be given, so that users
who are unable to view the image (e.g. because they have a very slow connection, or because they
are using a text-only browser, or because they are listening to the page being read out by a
hands-free automobile voice web browser, or simply because they are blind) are still able to
understand the message being conveyed.
The text must be given in the alt attribute, and must convey
the same message as the image specified in the src
attribute.
It is important to realize that the alternative text is a replacement for the image, not a description of the image.
A document can contain information in iconic form. The icon is intended to help users of visual browsers to recognize features at a glance.
In some cases, the icon is supplemental to a text label conveying the same meaning. In those
cases, the alt attribute must be present but must be empty.
In other cases, the icon has no text next to it describing what it means; the icon is supposed
to be self-explanatory. In those cases, an equivalent textual label must be given in the alt attribute.
Many pages include logos, insignia, flags, or emblems, which stand for a particular entity such as a company, organization, project, band, software package, country, or some such.
If the logo is being used to represent the entity, e.g. as a page heading, the alt attribute must contain the name of the entity being represented by
the logo. The alt attribute must not contain text like
the word "logo", as it is not the fact that it is a logo that is being conveyed, it's the entity
itself.
If the logo is being used next to the name of the entity that it represents, then the logo is
supplemental, and its alt attribute must instead be empty.
If the logo is merely used as decorative material (as branding, or, for example, as a side image in an article that mentions the entity to which the logo belongs), then the entry below on purely decorative images applies. If the logo is actually being discussed, then it is being used as a phrase or paragraph (the description of the logo) with an alternative graphical representation (the logo itself), and the first entry above applies.
Sometimes, an image just consists of text, and the purpose of the image is not to highlight the actual typographic effects used to render the text, but just to convey the text itself.
In such cases, the alt attribute must be present but must
consist of the same text as written in the image itself.
When an image is used to represent a character that cannot otherwise be represented in Unicode, for example gaiji, itaiji, or new characters such as novel currency symbols, the alternative text should be a more conventional way of writing the same thing, e.g. using the phonetic hiragana or katakana to give the character's pronunciation.
An image should not be used if characters would serve an identical purpose. Only when the text cannot be directly represented using text, e.g., because of decorations or because there is no appropriate character (as in the case of gaiji), would an image be appropriate.
In many cases, the image is actually just supplementary, and its presence merely reinforces the
surrounding text. In these cases, the alt attribute must be
present but its value must be the empty string.
In general, an image falls into this category if removing the image doesn't make the page any less useful, but including the image makes it a lot easier for users of visual browsers to understand the concept.
Sometimes, an image is not critical to the content, but is nonetheless neither purely
decorative nor entirely redundant with the text. In these cases, the alt attribute must be present, and its value should either be the
empty string, or a textual representation of the information that the image conveys. If the image
has a caption giving the image's title, then the alt
attribute's value must not be empty (as that would be quite confusing for non-visual readers).
If an image is decorative but isn't especially page-specific — for example an image that forms part of a site-wide design scheme — the image should be specified in the site's CSS, not in the markup of the document.
However, a decorative image that isn't discussed by the surrounding text but still has some
relevance can be included in a page using the img element. Such images are
decorative, but still form part of the content. In these cases, the alt attribute must be present but its value must be the empty
string.
When a picture has been sliced into smaller image files that are then displayed together to
form the complete picture again, one of the images must have its alt attribute set as per the relevant rules that would be appropriate
for the picture as a whole, and then all the remaining images must have their alt attribute set to the empty string.
Generally, image maps should be used instead of slicing an image for links.
However, if an image is indeed sliced and any of the components of the sliced picture are the
sole contents of links, then one image per link must have alternative text in its alt attribute representing the purpose of the link.
In some cases, the image is a critical part of the content. This could be the case, for instance, on a page that is part of a photo gallery. The image is the whole point of the page containing it.
How to provide alternative text for an image that is a key part of the content depends on the image's provenance.
When it is possible for detailed alternative text to be provided, for example if the image is
part of a series of screenshots in a magazine review, or part of a comic strip, or is a
photograph in a blog entry about that photograph, text that can serve as a substitute for the
image must be given as the contents of the alt attribute.
In certain cases, the nature of the image might be such that providing thorough alternative text is impractical. For example, the image could be indistinct, or could be a complex fractal, or could be a detailed topographical map.
In these cases, the alt attribute must contain some
suitable alternative text, but it may be somewhat brief.
In some unfortunate cases, there might be no alternative text available at all, either because the image is obtained in some automated fashion without any associated alternative text (e.g., a webcam), or because the page is being generated by a script using user-provided images where the user did not provide suitable or usable alternative text (e.g. photograph sharing sites), or because the author does not themself know what the images represent (e.g. a blind photographer sharing an image on their blog).
In such cases, the alt attribute may be omitted, but one of
the following conditions must be met as well:
The img element is in a
figure element that contains a figcaption element that contains
content other than inter-element whitespace, and, ignoring the
figcaption element and its descendants, the figure element has no
flow content descendants other than inter-element whitespace and the
img element.
The title attribute is present and has a non-empty
value.
Generally authors should avoid using img elements for purposes other than showing
images.
If an img element is being used for purposes other than showing an image, e.g. as
part of a service to count page views, then the alt attribute
must be the empty string.
In such cases, the width and height attributes should both be set to zero.
This section does not apply to documents that are publicly accessible, or whose target audience is not necessarily personally known to the author, such as documents on a web site, emails sent to public mailing lists, or software documentation.
When an image is included in a private communication (such as an HTML email) aimed at a
specific person who is known to be able to view images, the alt
attribute may be omitted. However, even in such cases authors are strongly urged to include
alternative text (as appropriate according to the kind of image involved, as described in the
above entries), so that the email is still usable should the user use a mail client that does not
support images, or should the document be forwarded on to other users whose abilities might not
include easily seeing images.
Markup generators (such as WYSIWYG authoring tools) should, wherever possible, obtain alternative text from their users. However, it is recognized that in many cases, this will not be possible.
For images that are the sole contents of links, markup generators should examine the link target to determine the title of the target, or the URL of the target, and use information obtained in this manner as the alternative text.
For images that have captions, markup generators should use the figure and
figcaption elements, or the title attribute, to
provide the image's caption.
As a last resort, implementers should either set the alt
attribute to the empty string, under the assumption that the image is a purely decorative image
that doesn't add any information but is still specific to the surrounding content, or omit the
alt attribute altogether, under the assumption that the image is
a key part of the content.
Markup generators should generally avoid using the image's own filename as the alternative text. Similarly, markup generators should avoid generating alternative text from any content that will be equally available to presentation user agents (e.g., web browsers).
A conformance checker must report the lack of an alt
attribute as an error unless one of the conditions listed below applies:
The img element is in a figure element that satisfies the conditions described above.
The img element has a title attribute with a
value that is not the empty string (also as described
above).
The conformance checker has been configured to assume that the document is an email or document intended for a specific person who is known to be able to view images.
The img element has a (non-conforming) generator-unable-to-provide-required-alt
attribute whose value is the empty string. A conformance checker that is not reporting the lack
of an alt attribute as an error must also not report the
presence of the empty generator-unable-to-provide-required-alt
attribute as an error. (This case does not represent a case where the document is conforming,
only that the generator could not determine appropriate alternative text — validators are
not required to show an error in this case, because such an error might encourage markup
generators to include bogus alternative text purely in an attempt to silence validators.
Naturally, conformance checkers may report the lack of an alt attribute as an error even in the presence of the generator-unable-to-provide-required-alt
attribute; for example, there could be a user option to report all conformance errors
even those that might be the more or less inevitable result of using a markup
generator.)
iframe elementSupport in all current engines.
Support in all current engines.
src — Address of the resource
srcdoc — A document to render in the iframe
name — Name of content navigable
sandbox — Security rules for nested content
allow — Permissions policy to be applied to the iframe's contents
allowfullscreen — Whether to allow the iframe's contents to use requestFullscreen()
width — Horizontal dimension
height — Vertical dimension
referrerpolicy — Referrer policy for fetches initiated by the element
loading — Used when determining loading deferral
The iframe element represents its content navigable.
The src attribute
gives the URL of a page that the element's content navigable is to
contain. The attribute, if present, must be a valid non-empty URL potentially surrounded by
spaces. If the itemprop attribute is specified on an
iframe element, then the src attribute must
also be specified.
Support in all current engines.
The srcdoc
attribute gives the content of the page that the element's content navigable is to
contain. The value of the attribute is used to construct an iframe srcdoc document, which is a Document whose
URL matches about:srcdoc.
The srcdoc attribute, if present, must have a value
using the HTML syntax that consists of the following syntactic components, in the
given order:
html element.The iframe HTML element post-connection steps, given
insertedNode, are:
Create a new child navigable for insertedNode.
If insertedNode has a sandbox
attribute, then parse the sandboxing
directive given the attribute's value and insertedNode's
iframe sandboxing flag set.
Process the iframe attributes for insertedNode, with
initialInsertion set to true.
The iframe HTML element removing steps, given
removedNode, are to destroy a child navigable given
removedNode.
Whenever an iframe element with a non-null content navigable has its
srcdoc attribute set, changed, or removed, the user
agent must process the iframe attributes.
Similarly, whenever an iframe element with a non-null content
navigable but with no srcdoc attribute specified
has its src attribute set, changed, or removed, the user
agent must process the iframe attributes.
To process the iframe attributes for an element element,
with an optional boolean initialInsertion (default false):
If element's srcdoc attribute is
specified, then:
Set element's current navigation was lazy loaded boolean to false.
If the will lazy load element steps given element return true, then:
Set element's lazy load resumption steps to the rest of this algorithm starting with the step labeled navigate to the srcdoc resource.
Set element's current navigation was lazy loaded boolean to true.
Start intersection-observing a lazy loading element for element.
Return.
Navigate to the srcdoc resource: Navigate an iframe or
frame given element, about:srcdoc, the empty
string, and the value of element's srcdoc
attribute.
The resulting Document must be considered an iframe srcdoc document.
Otherwise:
Let url be the result of running the shared attribute processing steps
for iframe and frame elements given element and
initialInsertion.
If url is null, then return.
If url matches about:blank and
initialInsertion is true, then:
Run the iframe load event steps given element.
Return.
Let referrerPolicy be the current state of element's referrerpolicy content attribute.
Set element's current navigation was lazy loaded boolean to false.
If the will lazy load element steps given element return true, then:
Set element's lazy load resumption steps to the rest of this algorithm starting with the step labeled navigate.
Set element's current navigation was lazy loaded boolean to true.
Start intersection-observing a lazy loading element for element.
Return.
Navigate: Navigate an iframe or frame
given element, url, and referrerPolicy.
Each Document has an iframe load in progress flag and a mute
iframe load flag. When a Document is created, these flags must be unset for
that Document.
An iframe element whose current navigation was lazy loaded boolean is
false potentially delays the load event.
Each iframe element has an associated null or
DOMHighResTimeStamp pending resource-timing start time,
initially set to null.
The name
attribute, if present, must be a valid navigable target name. The given value is
used to name the element's content navigable if present when that is created.
Support in all current engines.
When the attribute is set, the content is treated as being from a unique opaque origin, forms, scripts, and various potentially
annoying APIs are disabled, and links are prevented from targeting other navigables. The allow-same-origin keyword causes the
content to be treated as being from its real origin instead of forcing it into an opaque origin; the allow-top-navigation keyword allows the
content to navigate its traversable navigable;
the allow-top-navigation-by-user-activation
keyword behaves similarly but allows such navigation only when the
browsing context's active window has transient
activation; the allow-top-navigation-to-custom-protocols
reenables navigations toward non fetch scheme to be handed off to external software; and the allow-forms, allow-modals, allow-orientation-lock, allow-pointer-lock, allow-popups, allow-presentation, allow-scripts, and allow-popups-to-escape-sandbox
keywords re-enable forms, modal dialogs, screen orientation lock, the pointer lock API, popups,
the presentation API, scripts, and the creation of unsandboxed auxiliary browsing contexts respectively. The allow-downloads keyword allows content to
perform downloads. [POINTERLOCK] [SCREENORIENTATION] [PRESENTATION]
The allow-top-navigation and allow-top-navigation-by-user-activation
keywords must not both be specified, as doing so is redundant; only allow-top-navigation will have an effect
in such non-conformant markup.
Similarly, the allow-top-navigation-to-custom-protocols
keyword must not be specified if either allow-top-navigation or allow-popups are specified, as doing so is
redundant.
When an iframe element's sandbox
attribute is set or changed while it has a non-null content navigable, the user
agent must parse the sandboxing directive
given the attribute's value and the iframe element's iframe
sandboxing flag set.
When an iframe element's sandbox
attribute is removed while it has a non-null content navigable, the user agent must
empty the iframe element's iframe sandboxing flag set.
The iframe element supports dimension attributes for cases where the
embedded content has specific dimensions (e.g. ad units have well-defined dimensions).
An iframe element never has fallback content, as it will always
create a new child navigable, regardless of whether the specified initial
contents are successfully used.
When the loading attribute's state is changed to the
Eager state, the user agent must run these
steps:
Let resumptionSteps be the iframe element's lazy load
resumption steps.
If resumptionSteps is null, then return.
Set the iframe's lazy load resumption steps to null.
Invoke resumptionSteps.
Descendants of iframe elements represent nothing. (In legacy user agents that do
not support iframe elements, the contents would be parsed as markup that could act as
fallback content.)
Support in all current engines.
The IDL attributes src, name, sandbox, and allow must
reflect the respective content attributes of the same name.
Support in all current engines.
The srcdoc setter steps
are:
Let compliantString be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, the given value, "HTMLIFrameElement srcdoc", and "script".
Set an attribute value given
this, srcdoc's local name, and
compliantString.
The supported tokens for sandbox's DOMTokenList are the allowed
values defined in the sandbox attribute and supported by
the user agent.
The allowFullscreen IDL attribute must
reflect the allowfullscreen content
attribute.
HTMLIFrameElement/referrerPolicy
Support in all current engines.
The loading IDL attribute must reflect the loading content attribute, limited to only known
values.
HTMLIFrameElement/contentDocument
Support in all current engines.
The contentDocument getter steps are to return the
this's content document.
HTMLIFrameElement/contentWindow
Support in all current engines.
The contentWindow getter steps are to return
this's content window.
embed elementSupport in all current engines.
Support in all current engines.
src — Address of the resource
type — Type of embedded resource
width — Horizontal dimension
height — Vertical dimension
The embed element provides an integration point for an external application or
interactive content.
If the itemprop attribute is specified on an
embed element, then the src attribute must also
be specified.
While any of the following conditions are occurring, any plugin instantiated for
the element must be removed, and the embed element represents
nothing:
The element has neither a src attribute nor a type attribute.
The element has a media element ancestor.
The element has an ancestor object element that is not showing its
fallback content.
Whenever an embed element that was potentially
active stops being potentially active, any
plugin that had been instantiated for that element must be unloaded.
The embed element potentially delays the load event.
The embed element supports dimension attributes.
The IDL attributes src and type each must reflect the respective content
attributes of the same name.
object elementSupport in all current engines.
Support in all current engines.
data — Address of the resource
type — Type of embedded resource
name — Name of content navigable
form — Associates the element with a form element
width — Horizontal dimension
height — Vertical dimension
Depending on the type of content instantiated by the
object element, the node also supports other
interfaces.
The object element can represent an external resource, which, depending on the
type of the resource, will either be treated as an image or as a child
navigable.
Whenever one of the following conditions occur:
object elements changes to or from showing its
fallback content,
classid attribute is set, changed, or
removed,
classid attribute is not present, and
its data attribute is set, changed, or removed,
classid attribute nor its
data attribute are present, and its type attribute is set, changed, or removed,
...the user agent must queue an element task on the DOM manipulation task
source given the object element to run the following steps to (re)determine
what the object element represents. This task
being queued or actively running must delay the load
event of the element's node document.
If the user has indicated a preference that this object element's fallback
content be shown instead of the element's usual behavior, then jump to the step below
labeled fallback.
If the element has an ancestor media element, or has an ancestor
object element that is not showing its fallback content, or if
the element is not in a document whose browsing
context is non-null, or if the element's node document is not fully
active, or if the element is still in the stack of open elements of an
HTML parser or XML parser, or if the element is not being
rendered, then jump to the step below labeled fallback.
If the data attribute is present and its value is
not the empty string, then:
If the type attribute is present and its value is
not a type that the user agent supports, then the user agent may jump to the step below labeled
fallback without fetching the content to examine its real type.
Let url be the result of encoding-parsing a URL given the data attribute's value, relative to the element's node
document.
If url is failure, then fire an
event named error at the element and jump to the step
below labeled fallback.
Let request be a new request whose
URL is url, client is the element's node document's
relevant settings object, destination is "object",
credentials mode is "include", mode is "navigate", initiator
type is "object", and whose use-URL-credentials
flag is set.
Fetch request.
Fetching the resource must delay the load event of the element's node document until the task that is queued by the networking task source once the resource has been fetched (defined next) has been run.
If the resource is not yet available (e.g. because the resource was not available in the cache, so that loading the resource required making a request over the network), then jump to the step below labeled fallback. The task that is queued by the networking task source once the resource is available must restart this algorithm from this step. Resources can load incrementally; user agents may opt to consider a resource "available" whenever enough data has been obtained to begin processing the resource.
If the load failed (e.g. there was an HTTP 404 error, there was a DNS error), fire an event named error
at the element, then jump to the step below labeled fallback.
Determine the resource type, as follows:
Let the resource type be unknown.
If the user agent is configured to strictly obey Content-Type headers for this resource, and the resource has associated Content-Type metadata, then let the resource type be the type specified in the resource's Content-Type metadata, and jump to the step below labeled handler.
Run the appropriate set of steps from the following list:
Let binary be false.
If the type specified in the resource's Content-Type
metadata is "text/plain", and the result of applying the rules for distinguishing if a resource is
text or binary to the resource is that the resource is not
text/plain, then set binary to true.
If the type specified in the resource's Content-Type
metadata is "application/octet-stream", then set binary to true.
If binary is false, then let the resource type be the type specified in the resource's Content-Type metadata, and jump to the step below labeled handler.
If there is a type attribute present on the
object element, and its value is not application/octet-stream,
then run the following steps:
If the attribute's value is a type that starts with "image/" that is
not also an XML MIME type, then let the resource type be the
type specified in that type attribute.
Jump to the step below labeled handler.
If there is a type attribute present on the
object element, then let the tentative type be the type
specified in that type attribute.
Otherwise, let tentative type be the computed type of the resource.
If tentative type is not
application/octet-stream, then let resource type be
tentative type and jump to the step below labeled
handler.
If applying the URL parser algorithm to the URL of the specified resource (after any redirects) results in a URL record whose path component matches a pattern that a plugin supports, then let resource type be the type that that plugin can handle.
Handler: Handle the content as given by the first of the following cases that matches:
image/"If the object element's content navigable is null, then
create a new child navigable for the element.
Let response be the response from fetch.
If response's URL does not match about:blank, then
navigate the element's content navigable to
response's URL using the element's
node document, with historyHandling set to
"replace".
The object element represents its content
navigable.
image/", and support
for images has not been disabledDestroy a child navigable given the object element.
Apply the image sniffing rules to determine the type of the image.
The object element represents the specified image.
If the image cannot be rendered, e.g. because it is malformed or in an unsupported format, jump to the step below labeled fallback.
The given resource type is not supported. Jump to the step below labeled fallback.
The element's contents are not part of what the object element
represents.
If the object element does not represent its content navigable,
then once the resource is completely loaded, queue an element task on the
DOM manipulation task source given the object element to fire an event named load
at the element.
Return.
Fallback: The object element represents the element's
children. This is the element's fallback content. Destroy a child
navigable given the element.
Due to the algorithm above, the contents of object elements act as fallback
content, used only when referenced resources can't be shown (e.g. because it returned a 404
error). This allows multiple object elements to be nested inside each other,
targeting multiple user agents with different capabilities, with the user agent picking the first
one it supports.
The object element potentially delays the load event.
The form attribute is used to explicitly associate the
object element with its form owner.
The object element supports dimension attributes.
Support in all current engines.
Support in all current engines.
Support in all current engines.
The IDL attributes data, type, and name each must reflect the respective content
attributes of the same name.
HTMLObjectElement/contentDocument
Support in all current engines.
The contentDocument getter steps are to return
this's content document.
HTMLObjectElement/contentWindow
Support in all current engines.
The willValidate, validity, and validationMessage attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the
constraint validation API. The form IDL attribute
is part of the element's forms API.
video elementSupport in all current engines.
Support in all current engines.
controls attribute: Interactive content.src attribute:
zero or more track elements, then
transparent, but with no media element descendants.src attribute: zero or more source elements, then
zero or more track elements, then
transparent, but with no media element descendants.src — Address of the resource
crossorigin — How the element handles crossorigin requests
poster — Poster frame to show prior to video playback
preload — Hints how much buffering the media resource will likely need
autoplay — Hint that the media resource can be started automatically when the page is loaded
playsinline — Encourage the user agent to display video content within the element's playback area
loop — Whether to loop the media resource
muted — Whether to mute the media resource by default
controls — Show user agent controls
width — Horizontal dimension
height — Vertical dimension
A video element is used for playing videos or movies, and audio files with
captions.
Content may be provided inside the video element. User agents
should not show this content to the user; it is intended for older web browsers which do
not support video, so that text can be shown to the users of these older browsers
informing them of how to access the video contents.
The video element is a media element whose media data is
ostensibly video data, possibly with associated audio data.
The src, crossorigin,
preload, autoplay,
loop, muted, and controls attributes are the attributes common to all media elements.
The playsinline attribute is a boolean
attribute. If present, it serves as a hint to the user agent that the video ought to be
displayed "inline" in the document by default, constrained to the element's playback area, instead
of being displayed fullscreen or in an independent resizable window.
A video element represents what is given for the first matching condition in the
list below:
readyState attribute is either HAVE_NOTHING, or HAVE_METADATA but no video data has yet been obtained at
all, or the element's readyState attribute is any
subsequent value but the media resource does not have a video channel)video element represents its poster frame, if any,
or else transparent black with no natural dimensions.video element is paused, the current playback position is the first frame of video,
and the element's show poster flag is setvideo element represents its poster frame, if any,
or else the first frame of the video.video element is paused, and the
frame of video corresponding to the current playback
position is not available (e.g. because the video is seeking or buffering)video element is neither potentially playing nor paused (e.g. when seeking or stalled)video element represents the last frame of the video to have
been rendered.video element is pausedvideo element represents the frame of video corresponding to
the current playback position.video element has a video channel and is potentially
playing)video element represents the frame of video at the continuously
increasing "current" position. When the
current playback position changes such that the last frame rendered is no longer the
frame corresponding to the current playback position in the video, the new frame
must be rendered.Frames of video must be obtained from the video track that was selected when the event loop last reached step 1.
The video element also represents any text track cues whose text track cue active flag is set and whose
text track is in the showing mode, and any
audio from the media resource, at the current playback position.
Any audio associated with the media resource must, if played, be played synchronized with the current playback position, at the element's effective media volume. The user agent must play the audio from audio tracks that were enabled when the event loop last reached step 1.
In addition to the above, the user agent may provide messages to the user (such as "buffering", "no video loaded", "error", or more detailed information) by overlaying text or icons on the video or other areas of the element's playback area, or in another appropriate manner.
User agents that cannot render the video may instead make the element represent a link to an external video playback utility or to the video data itself.
When a video element's media resource has a video channel, the
element provides a paint source whose width is the media resource's
natural width, whose height is the
media resource's natural
height, and whose appearance is the frame of video corresponding to the current playback position, if that is available, or else
(e.g. when the video is seeking or buffering) its previous appearance, if any, or else (e.g.
because the video is still loading the first frame) blackness.
The videoWidth IDL attribute must return the natural width of the video in CSS pixels. The videoHeight IDL attribute must return the natural height of the video in CSS pixels. If the element's readyState attribute is HAVE_NOTHING, then the attributes must return 0.
Whenever the natural width
or natural height of the video changes
(including, for example, because the selected video
track was changed), if the element's readyState
attribute is not HAVE_NOTHING, the user agent must
queue a media element task given the media element to fire an event named resize at the media element.
The video element supports dimension attributes.
In the absence of style rules to the contrary, video content should be rendered inside the element's playback area such that the video content is shown centered in the playback area at the largest possible size that fits completely within it, with the video content's aspect ratio being preserved. Thus, if the aspect ratio of the playback area does not match the aspect ratio of the video, the video will be shown letterboxed or pillarboxed. Areas of the element's playback area that do not contain the video represent nothing.
The natural width of a video element's playback area is the
natural width of the poster frame, if that is available and the
element currently represents its poster frame; otherwise, it is the natural width of the video resource, if that is
available; otherwise the natural width is missing.
The natural height of a video element's playback area is the
natural height of the poster frame, if that is available and the
element currently represents its poster frame; otherwise it is the natural height of the video resource, if that is
available; otherwise the natural height is missing.
The default object size is a width of 300 CSS pixels and a height of 150 CSS pixels. [CSSIMAGES]
User agents should provide controls to enable or disable the display of closed captions, audio description tracks, and other additional data associated with the video stream, though such features should, again, not interfere with the page's normal rendering.
User agents may allow users to view the video content in manners more suitable to the user,
such as fullscreen or in an independent resizable window. User agents may even trigger such a
viewing mode by default upon playing a video, although they should not do so when the playsinline attribute is specified. As with the other user
interface features, controls to enable this should not interfere with the page's normal rendering
unless the user agent is exposing a user
interface. In such an independent viewing mode, however, user agents may make full user
interfaces visible, even if the controls attribute is
absent.
User agents may allow video playback to affect system features that could interfere with the user's experience; for example, user agents could disable screensavers while video playback is in progress.
The playsInline IDL attribute must reflect
the playsinline content attribute.
audio elementSupport in all current engines.
Support in all current engines.
controls attribute: Interactive content.controls attribute: Palpable content.src attribute:
zero or more track elements, then
transparent, but with no media element descendants.src attribute: zero or more source elements, then
zero or more track elements, then
transparent, but with no media element descendants.src — Address of the resource
crossorigin — How the element handles crossorigin requests
preload — Hints how much buffering the media resource will likely need
autoplay — Hint that the media resource can be started automatically when the page is loaded
loop — Whether to loop the media resource
muted — Whether to mute the media resource by default
controls — Show user agent controls
An audio element represents a sound or audio stream.
Content may be provided inside the audio element. User agents
should not show this content to the user; it is intended for older web browsers which do
not support audio, so that text can be shown to the users of these older browsers
informing them of how to access the audio contents.
The audio element is a media element whose media data is
ostensibly audio data.
The src, crossorigin,
preload, autoplay,
loop, muted, and controls attributes are the attributes common to all media elements.
track elementSupport in all current engines.
Support in all current engines.
kind — The type of text track
src — Address of the resource
srclang — Language of the text track
label — User-visible label
default — Enable the track if no other text track is more suitable
The track element allows authors to specify explicit external timed text tracks for media elements. It
does not represent anything on its own.
The kind attribute is
an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
subtitles
| Subtitles | Transcription or translation of the dialogue, suitable for when the sound is available but not understood (e.g. because the user does not understand the language of the media resource's audio track). Overlaid on the video. |
captions
| Captions | Transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information, suitable for when sound is unavailable or not clearly audible (e.g. because it is muted, drowned-out by ambient noise, or because the user is deaf). Overlaid on the video; labeled as appropriate for the hard-of-hearing. |
descriptions
| Descriptions | Textual descriptions of the video component of the media resource, intended for audio synthesis when the visual component is obscured, unavailable, or not usable (e.g. because the user is interacting with the application without a screen while driving, or because the user is blind). Synthesized as audio. |
chapters
| Chapters metadata | Tracks intended for use from script. Not displayed by the user agent. |
metadata
|
The attribute's missing value default is the subtitles state, and its invalid value default is the metadata state.
When the element's src attribute is set, run these steps:
Let trackURL be failure.
Let value be the element's src attribute
value.
If value is not the empty string, then set trackURL to the result of encoding-parsing-and-serializing a URL given value, relative to the element's node document.
Set the element's track URL to trackURL if it is not failure; otherwise to the empty string.
If the element's track URL identifies a WebVTT resource, and the element's kind attribute is not in the chapters metadata or metadata state, then the WebVTT file must be a
WebVTT file using cue text. [WEBVTT]
The value of the label attribute, if the attribute is
present, must not be the empty string. Furthermore, there must not be two track
element children of the same media element whose kind attributes are in the same state, whose srclang attributes are both missing or have values that
represent the same language, and whose label attributes are
again both missing or both have the same value.
Each media element must have no more than one track element child
whose kind attribute is in the subtitles or captions state and whose default attribute is specified.
Each media element must have no more than one track element child
whose kind attribute is in the description state and whose default attribute is specified.
Each media element must have no more than one track element child
whose kind attribute is in the chapters metadata state and whose default attribute is specified.
The track IDL
attribute must, on getting, return the track element's text track's
corresponding TextTrack object.
Support in all current engines.
The src, srclang, label, and default IDL
attributes must reflect the respective content attributes of the same name. The kind IDL attribute
must reflect the content attribute of the same name, limited to only known
values.
HTMLMediaElement objects (audio and video, in this
specification) are simply known as media elements.
Support in all current engines.
Media elements are used to present audio data, or video and audio data, to the user. This is referred to as media data in this section, since this section applies equally to media elements for audio or for video. The term media resource is used to refer to the complete set of media data, e.g. the complete video file, or complete audio file.
A media resource can have multiple audio and video tracks. For the purposes of a
media element, the video data of the media resource is only that of the
currently selected track (if any) as given by the element's videoTracks attribute when the event loop last
reached step 1, and the audio data of the media resource is the result of mixing all
the currently enabled tracks (if any) given by the element's audioTracks attribute when the event loop last
reached step 1.
To queue a media element task with a media element element and a series of steps steps, queue an element task on the media element's media element event task source given element and steps.
Support in all current engines.
All media elements have an associated error status, which
records the last error the element encountered since its resource selection algorithm was last invoked. The
error attribute,
on getting, must return the MediaError object created for this last error, or null if
there has not been an error.
The message
getter steps are to return this's message.
If the itemprop attribute is specified on the media
element, then the src attribute must also be
specified.
If a media element is created with a
src attribute, the user agent must immediately invoke the
media element's resource selection
algorithm.
If a src attribute of a media element is set
or changed, the user agent must invoke the media element's media element load
algorithm. (Removing the src attribute does
not do this, even if there are source elements present.)
Support in all current engines.
The src IDL
attribute on media elements must reflect the
content attribute of the same name.
Support in all current engines.
The srcObject IDL attribute, on getting, must return the
element's assigned media provider object, if any, or null otherwise. On setting, it
must set the element's assigned media provider object to the new value, and then
invoke the element's media element load algorithm.
A media resource can be described in terms of its type, specifically a
MIME type, in some cases with a codecs parameter. (Whether the
codecs parameter is allowed or not depends on the MIME type.)
[RFC6381]
Types are usually somewhat incomplete descriptions; for example "video/mpeg" doesn't say anything except what the container type is, and even a
type like "video/mp4; codecs="avc1.42E01E, mp4a.40.2"" doesn't
include information like the actual bitrate (only the maximum bitrate). Thus, given a type, a user
agent can often only know whether it might be able to play media of that type (with
varying levels of confidence), or whether it definitely cannot play media of that
type.
The MIME type "application/octet-stream" with no parameters is never
a type that the user agent knows it cannot render. User agents must treat that type
as equivalent to the lack of any explicit Content-Type metadata
when it is used to label a potential media resource.
The canPlayType(type) method must return
the empty string if type is a type
that the user agent knows it cannot render or is the type
"application/octet-stream"; it must return "probably" if
the user agent is confident that the type represents a media resource that it can
render if used in with this audio or video element; and it must return
"maybe" otherwise. Implementers are encouraged to
return "maybe" unless the type can be
confidently established as being supported or not. Generally, a user agent should never return
"probably" for a type that allows the codecs parameter if that parameter is not present.
The resource selection algorithm defined
below describes exactly when the networkState
attribute changes value and what events fire to indicate changes in this state.
All media elements have a can autoplay flag, which must begin in the true state, and a delaying-the-load-event flag, which must begin in the false state. While the delaying-the-load-event flag is true, the element must delay the load event of its document.
When a media element is to forget the media element's media-resource-specific
tracks, the user agent must remove from the media element's list of text
tracks all the media-resource-specific
text tracks, then empty the media element's audioTracks attribute's AudioTrackList object,
then empty the media element's videoTracks
attribute's VideoTrackList object. No events (in particular, no removetrack events) are fired as part of this; the error and emptied
events, fired by the algorithms that invoke this one, can be used instead.
The preload
attribute is an enumerated attribute with the following keywords and
states:
| Keyword | State | Brief description |
|---|---|---|
auto
| Automatic | Hints to the user agent that the user agent can put the user's needs first without risk to the server, up to and including optimistically downloading the entire resource. |
| (the empty string) | ||
none
| None | Hints to the user agent that either the author does not expect the user to need the media resource, or that the server wants to minimize unnecessary traffic. This state does not provide a hint regarding how aggressively to actually download the media resource if buffering starts anyway (e.g. once the user hits "play"). |
metadata
| Metadata | Hints to the user agent that the author does not expect the user to need the media resource, but that fetching the resource metadata (dimensions, track list, duration, etc.), and maybe even the first few frames, is reasonable. If the user agent precisely fetches no more than the metadata, then the media element will end up with its readyState attribute set to HAVE_METADATA; typically though, some frames will be obtained as well and it will probably be HAVE_CURRENT_DATA or HAVE_FUTURE_DATA.
When the media resource is playing, hints to the user agent that bandwidth is to be considered scarce, e.g. suggesting throttling the download so that the media data is obtained at the slowest possible rate that still maintains consistent playback.
|
The attribute's missing value default and invalid value default are both implementation-defined, though the Metadata state is suggested as a compromise between reducing server load and providing an optimal user experience.
The attribute can be changed even once the media resource is being buffered or played; the descriptions in the table above are to be interpreted with that in mind.
The preload attribute is intended to provide a hint to
the user agent about what the author thinks will lead to the best user experience. The attribute
may be ignored altogether, for example based on explicit user preferences or based on the
available connectivity.
The preload
IDL attribute must reflect the content attribute of the same name, limited to
only known values.
User agents may discard previously buffered data.
If the media resource has a discontinuous timeline, the user agent must extend the timeline used at the start of the resource across the entire resource, so that the media timeline of the media resource increases linearly starting from the earliest possible position (as defined below), even if the underlying media data has out-of-order or even overlapping time codes.
In the rare case of a media resource that does not have an explicit timeline, the
zero time on the media timeline should correspond to the first frame of the
media resource. In the even rarer case of a media resource with no
explicit timings of any kind, not even frame durations, the user agent must itself determine the
time for each frame in an implementation-defined manner.
If, in the case of a resource with no timing information, the user agent will nonetheless be able to seek to an earlier point than the first frame originally provided by the server, then the zero time should correspond to the earliest seekable time of the media resource; otherwise, it should correspond to the first frame received from the server (the point in the media resource at which the user agent began receiving the stream).
In any case, the user agent must ensure that the earliest possible position (as defined below) using the established media timeline, is greater than or equal to zero.
The media timeline also has an associated clock. Which clock is used is user-agent defined, and may be media resource-dependent, but it should approximate the user's wall clock.
When the earliest possible position changes, then: if the current playback
position is before the earliest possible position, the user agent must seek to the earliest possible position; otherwise, if
the user agent has not fired a timeupdate event at
the element in the past 15 to 250ms and is not still running event handlers for such an event,
then the user agent must queue a media element task given the media
element to fire an event named timeupdate at the element.
If at any time the user agent learns that an audio or video track has ended and all media data relating to that track corresponds to parts of the media timeline that are before the earliest possible position, the user agent may queue a media element task given the media element to run these steps:
Remove the track from the audioTracks
attribute's AudioTrackList object or the videoTracks attribute's VideoTrackList object
as appropriate.
Fire an event named removetrack at the media element's
aforementioned AudioTrackList or VideoTrackList object, using
TrackEvent, with the track attribute
initialized to the AudioTrack or VideoTrack object representing the
track.
The user agent must determine the duration of the media resource before playing
any part of the media data and before setting readyState to a value greater than or equal to HAVE_METADATA, even if doing so requires fetching multiple
parts of the resource.
When the length of the media resource changes to a known value
(e.g. from being unknown to known, or from a previously established length to a new length) the
user agent must queue a media element task given the media element to
fire an event named durationchange at the media element. (The
event is not fired when the duration is reset as part of loading a new media resource.) If the
duration is changed such that the current playback position ends up being greater
than the time of the end of the media resource, then the user agent must also seek to the time of the end of the media resource.
The getStartDate() method must return a new Date object representing the current
timeline offset.
The loop
attribute is a boolean attribute that, if specified, indicates that the media
element is to seek back to the start of the media resource upon reaching the
end.
Support in all current engines.
The loop IDL
attribute must reflect the content attribute of the same name.
Media elements have a ready state, which describes to what degree they are ready to be rendered at the current playback position. The possible values are as follows; the ready state of a media element at any particular time is the greatest value describing the state of the element:
HAVE_NOTHING (numeric value 0)No information regarding the media resource is available. No data for the
current playback position is available. Media
elements whose networkState attribute are set
to NETWORK_EMPTY are always in the HAVE_NOTHING state.
HAVE_METADATA (numeric value 1)Enough of the resource has been obtained that the duration of the resource is available.
In the case of a video element, the dimensions of the video are also available. No
media data is available for the immediate current playback
position.
HAVE_CURRENT_DATA (numeric value 2)Data for the immediate current playback position is available, but either not
enough data is available that the user agent could successfully advance the current
playback position in the direction of playback at all without immediately
reverting to the HAVE_METADATA state, or there is no
more data to obtain in the direction of playback. For example, in video this
corresponds to the user agent having data from the current frame, but not the next frame, when
the current playback position is at the end of the current frame; and to when playback has ended.
HAVE_FUTURE_DATA (numeric value 3)Data for the immediate current playback position is available, as well as
enough data for the user agent to advance the current playback position in the
direction of playback at least a little without immediately reverting to the HAVE_METADATA state, and the text tracks are
ready. For example, in video this corresponds to the user agent having data for at least
the current frame and the next frame when the current playback position is at the
instant in time between the two frames, or to the user agent having the video data for the
current frame and audio data to keep playing at least a little when the current playback
position is in the middle of a frame. The user agent cannot be in this state if playback has ended, as the current playback position
can never advance in this case.
HAVE_ENOUGH_DATA (numeric value 4)All the conditions described for the HAVE_FUTURE_DATA state are met, and, in addition,
either of the following conditions is also true:
playbackRate, would not overtake the available data
before playback reaches the end of the media resource.When the ready state of a media element whose networkState is not NETWORK_EMPTY changes, the user agent must follow the steps
given below:
Apply the first applicable set of substeps from the following list:
HAVE_NOTHING,
and the new ready state is HAVE_METADATAQueue a media element task given the media element to fire an event named loadedmetadata at the element.
HAVE_METADATA and the new ready state is HAVE_CURRENT_DATA or greaterIf this is the first time this occurs for this media
element since the load() algorithm was last
invoked, the user agent must queue a media element task given the media
element to fire an event named loadeddata at the element.
If the new ready state is HAVE_FUTURE_DATA
or HAVE_ENOUGH_DATA, then the relevant steps
below must then be run also.
HAVE_FUTURE_DATA or more, and the new ready state is
HAVE_CURRENT_DATA or lessIf the media element was potentially
playing before its readyState attribute
changed to a value lower than HAVE_FUTURE_DATA, and the element has not
ended playback, and playback has not stopped due to errors,
paused for user interaction, or paused for in-band content, the user
agent must queue a media element task given the media element to
fire an event named timeupdate at the element, and queue a media
element task given the media element to fire an event named waiting at the element.
HAVE_CURRENT_DATA or less, and the new ready state
is HAVE_FUTURE_DATAThe user agent must queue a media element task given the media
element to fire an event named canplay at the element.
If the element's paused attribute is false, the user
agent must notify about playing for the element.
HAVE_ENOUGH_DATAIf the previous ready state was HAVE_CURRENT_DATA or less, the user agent must
queue a media element task given the media element to fire an event named canplay at the element, and, if the element's paused attribute is false, notify about playing
for the element.
The user agent must queue a media element task given the media
element to fire an event named canplaythrough at the element.
If the element is not eligible for autoplay, then the user agent must abort these substeps.
The user agent may run the following substeps:
paused attribute to false.play at the element.Alternatively, if the element is a video element, the user agent may start
observing whether the element intersects the
viewport. When the element starts intersecting
the viewport, if the element is still eligible for autoplay, run the
substeps above. Optionally, when the element stops intersecting the viewport, if the can autoplay flag is still
true and the autoplay attribute is still specified,
run the following substeps:
pause at the element.The autoplay attribute is a boolean attribute.
When present, the user agent (as described in the algorithm described herein)
will automatically begin playback of the media resource as soon as it can do so
without stopping.
Support in all current engines.
The autoplay IDL attribute must reflect the
content attribute of the same name.
It is possible for a media element to have both ended playback and paused for user interaction at the same time.
When a media element that is potentially playing stops playing
because it has paused for user interaction, the user agent must queue a media
element task given the media element to fire
an event named timeupdate at the element.
A media element is said to have paused for in-band content when its
paused attribute is false, the readyState attribute is either HAVE_FUTURE_DATA or HAVE_ENOUGH_DATA and the user agent has suspended
playback of the media resource in order to play content that is temporally anchored
to the media resource and has a nonzero length, or to play content that is
temporally anchored to a segment of the media resource but has a length longer than
that segment.
When the current playback position reaches the end of the media resource when the direction of playback is forwards, then the user agent must follow these steps:
If the media element has a loop
attribute specified, then seek to the earliest
possible position of the media resource and return.
As defined above, the ended IDL attribute starts
returning true once the event loop returns to step 1.
Queue a media element task given the media element and the following steps:
Fire an event named timeupdate at the media element.
If the media element has ended playback, the direction of playback is forwards, and paused is false, then:
Set the paused attribute to true.
Fire an event named pause at the media element.
Take pending play promises and reject pending play promises
with the result and an "AbortError"
DOMException.
Fire an event named ended at the media element.
When the current playback position reaches the earliest possible
position of the media resource when the direction of playback is
backwards, then the user agent must only queue a media element task given the
media element to fire an event named timeupdate at the element.
When the defaultPlaybackRate or playbackRate attributes change value (either by being set
by script or by being changed directly by the user agent, e.g. in response to user control) the
user agent must queue a media element task given the media element to
fire an event named ratechange at the media element. The user
agent must process attribute changes smoothly and must not introduce any perceivable gaps or
muting of playback in response.
The preservesPitch getter steps are to return true if a
pitch-preserving algorithm is in effect during playback. The setter steps are to correspondingly
switch the pitch-preserving algorithm on or off, without any perceivable gaps or muting of
playback. By default, such a pitch-preserving algorithm must be in effect (i.e., the getter will
initially return true).
The played
attribute must return a new static normalized TimeRanges object that
represents the ranges of points on the media timeline of the media
resource reached through the usual monotonic increase of the current playback
position during normal playback, if any, at the time the attribute is evaluated.
When a media element is potentially playing and
its Document is a fully active Document, its current
playback position must increase monotonically at the element's playbackRate units of media time per unit time of the
media timeline's clock. (This specification always refers to this as an
increase, but that increase could actually be a decrease if the element's playbackRate is negative.)
Any time the user agent provides a stable state, the official playback position must be set to the current playback position.
While the direction of playback is backwards, any corresponding audio must be
muted. While the element's playbackRate is so low or so high that the user agent
cannot play audio usefully, the corresponding audio must also be muted. If the element's playbackRate is not 1.0 and preservesPitch is true, the user agent must apply pitch
adjustment to preserve the original pitch of the audio. Otherwise, the user agent must speed up
or slow down the audio without any pitch adjustment.
When a media element is potentially playing, its audio data played must be synchronized with the current playback position, at the element's effective media volume. The user agent must play the audio from audio tracks that were enabled when the event loop last reached step 1.
When a media element is not potentially playing, audio must not play for the element.
Media elements that are potentially playing while not in a document must not play any video, but should play any audio component. Media elements must not stop playing just because all references to them have been removed; only once a media element is in a state where no further audio could ever be played by that element may the element be garbage collected.
When a text track cue is removed from the list of cues of a text track that is in the list of text tracks for a media element, and whenever a text track is removed from the list of text tracks of a media element, if the media element's show poster flag is not set, then the user agent must run the time marches on steps.
When the current playback position of a media element changes (e.g. due to playback or seeking), the user agent must run the time marches on steps. To support use cases that depend on the timing accuracy of cue event firing, such as synchronizing captions with shot changes in a video, user agents should fire cue events as close as possible to their position on the media timeline, and ideally within 20 milliseconds. If the current playback position changes while the steps are running, then the user agent must wait for the steps to complete, and then must immediately rerun the steps. These steps are thus run as often as possible or needed.
For the purposes of the algorithm above, a text track cue is considered to be part of a text track only if it is listed in the text track list of cues, not merely if it is associated with the text track.
When a media element is removed
from a Document, the user agent must run the following steps:
Await a stable state, allowing the task that removed the media element from the
Document to continue. The synchronous section consists of all the
remaining steps of this algorithm. (Steps in the synchronous section are marked with
⌛.)
⌛ If the media element is in a document, return.
⌛ Run the internal pause steps for the media element.
User agents should adopt a very liberal and optimistic view of what is seekable. User agents should also buffer recent content where possible to enable seeking to be fast.
Media resources might be internally scripted or interactive. Thus, a media element could play in a non-linear fashion. If this happens, the user agent must act as if the algorithm for seeking was used whenever the current playback position changes in a discontinuous fashion (so that the relevant events fire).
A media resource can have multiple embedded audio and video tracks. For example, in addition to the primary video and audio tracks, a media resource could have foreign-language dubbed dialogues, director's commentaries, audio descriptions, alternative angles, or sign-language overlays.
The videoTracks attribute of a media element
must return a live VideoTrackList object representing the video tracks
available in the media element's media resource.
AudioTrackList and VideoTrackList objectsSupport in all current engines.
Support in all current engines.
Support in all current engines.
The AudioTrackList and VideoTrackList interfaces are used by
attributes defined in the previous section.
Support in all current engines.
Support in all current engines.
An AudioTrackList object represents a dynamic list of zero or more audio tracks,
of which zero or more can be enabled at a time. Each audio track is represented by an
AudioTrack object.
A VideoTrackList object represents a dynamic list of zero or more video tracks, of
which zero or one can be selected at a time. Each video track is represented by a
VideoTrack object.
Tracks in AudioTrackList and VideoTrackList objects must be
consistently ordered. If the media resource is in a format that defines an order,
then that order must be used; otherwise, the order must be the relative order in which the tracks
are declared in the media resource. The order used is called the natural order
of the list.
The AudioTrackList length and VideoTrackList
length
attribute getters must return the number of tracks represented by their objects at the time of
getting.
The supported property indices of AudioTrackList and
VideoTrackList objects at any instant are the numbers from zero to the number of
tracks represented by the respective object minus one, if any tracks are represented. If an
AudioTrackList or VideoTrackList object represents no tracks, it has no
supported property indices.
To determine the value of an indexed property for a
given index index in an AudioTrackList or VideoTrackList
object list, the user agent must return the AudioTrack or
VideoTrack object that represents the indexth track in list.
The AudioTrackList getTrackById(id) and
VideoTrackList getTrackById(id) methods must
return the first AudioTrack or VideoTrack object (respectively) in the
AudioTrackList or VideoTrackList object (respectively) whose identifier
is equal to the value of the id argument (in the natural order of the list, as defined
above). When no tracks match the given argument, the methods must return null.
The AudioTrack and VideoTrack objects represent specific tracks of a
media resource. Each track can have an identifier, category, label, and language.
These aspects of a track are permanent for the lifetime of the track; even if a track is removed
from a media resource's AudioTrackList or VideoTrackList
objects, those aspects do not change.
In addition, AudioTrack objects can each be enabled or disabled; this is the audio
track's enabled state. When an AudioTrack is created, its enabled state
must be set to false (disabled). The resource fetch
algorithm can override this.
Similarly, a single VideoTrack object per VideoTrackList object can
be selected, this is the video track's selection state. When a VideoTrack is
created, its selection state must be set to false (not selected). The resource fetch algorithm can override this.
The AudioTrack id and VideoTrack id attributes must return the
identifier of the track, if it has one, or the empty string otherwise. If the media
resource is in a format that supports media fragment syntax, the identifier
returned for a particular track must be the same identifier that would enable the track if used as
the name of a track in the track dimension of such a fragment. [INBAND]
The AudioTrack kind and VideoTrack kind attributes must return the
category of the track, if it has one, or the empty string otherwise.
The category of a track is the string given in the first column of the table below that is the
most appropriate for the track based on the definitions in the table's second and third columns,
as determined by the metadata included in the track in the media resource. The cell
in the third column of a row says what the category given in the cell in the first column of that
row applies to; a category is only appropriate for an audio track if it applies to audio tracks,
and a category is only appropriate for video tracks if it applies to video tracks. Categories must
only be returned for AudioTrack objects if they are appropriate for audio, and must
only be returned for VideoTrack objects if they are appropriate for video.
For Ogg files, the Role header field of the track gives the relevant metadata. For DASH media
resources, the Role element conveys the information. For WebM, only the
FlagDefault element currently maps to a value. Sourcing In-band
Media Resource Tracks from Media Containers into HTML has further details.
[OGGSKELETONHEADERS] [DASH] [WEBMCG] [INBAND]
| Category | Definition | Applies to... | Examples |
|---|---|---|---|
"alternative"
| A possible alternative to the main track, e.g. a different take of a song (audio), or a different angle (video). | Audio and video. | Ogg: "audio/alternate" or "video/alternate"; DASH: "alternate" without "main" and "commentary" roles, and, for audio, without the "dub" role (other roles ignored). |
"captions"
| A version of the main video track with captions burnt in. (For legacy content; new content would use text tracks.) | Video only. | DASH: "caption" and "main" roles together (other roles ignored). |
"descriptions"
| An audio description of a video track. | Audio only. | Ogg: "audio/audiodesc". |
"main"
| The primary audio or video track. | Audio and video. | Ogg: "audio/main" or "video/main"; WebM: the "FlagDefault" element is set; DASH: "main" role without "caption", "subtitle", and "dub" roles (other roles ignored). |
"main-desc"
| The primary audio track, mixed with audio descriptions. | Audio only. | AC3 audio in MPEG-2 TS: bsmod=2 and full_svc=1. |
"sign"
| A sign-language interpretation of an audio track. | Video only. | Ogg: "video/sign". |
"subtitles"
| A version of the main video track with subtitles burnt in. (For legacy content; new content would use text tracks.) | Video only. | DASH: "subtitle" and "main" roles together (other roles ignored). |
"translation"
| A translated version of the main audio track. | Audio only. | Ogg: "audio/dub". DASH: "dub" and "main" roles together (other roles ignored). |
"commentary"
| Commentary on the primary audio or video track, e.g. a director's commentary. | Audio and video. | DASH: "commentary" role without "main" role (other roles ignored). |
"" (empty string)
| No explicit kind, or the kind given by the track's metadata is not recognized by the user agent. | Audio and video. |
The AudioTrack label and VideoTrack label attributes must return the
label of the track, if it has one, or the empty string otherwise. [INBAND]
The AudioTrack language and VideoTrack language attributes must
return the BCP 47 language tag of the language of the track, if it has one, or the empty string
otherwise. If the user agent is not able to express that language as a BCP 47 language tag (for
example because the language information in the media resource's format is a
free-form string without a defined interpretation), then the method must return the empty string,
as if the track had no language. [INBAND]
Whenever an audio track in an AudioTrackList that was
disabled is enabled, and whenever one that was enabled is disabled, the user agent must
queue a media element task given the media element to fire an event named change at the AudioTrackList object.
An audio track that has no data for a particular position on the media timeline, or that does not exist at that position, must be interpreted as being silent at that point on the timeline.
Whenever a track in a VideoTrackList that was previously
not selected is selected, and whenever the selected track in a VideoTrackList is
unselected without a new track being selected in its stead, the user agent must queue a
media element task given the media element to fire an event named change at the VideoTrackList object. This task must be queued
before the task that fires the resize event, if any.
A video track that has no data for a particular position on the media timeline must be interpreted as being transparent black at that point on the timeline, with the same dimensions as the last frame before that position, or, if the position is before all the data for that track, the same dimensions as the first frame for that track. A track that does not exist at all at the current position must be treated as if it existed but had no data.
The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes,
by all objects implementing the AudioTrackList and VideoTrackList
interfaces:
| Event handler | Event handler event type |
|---|---|
onchange Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? Support in all current engines. Firefox31+Safari7+Chrome33+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android4.4+Samsung Internet?Opera Android? Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | change
|
onaddtrack Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? Support in all current engines. Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | addtrack
|
onremovetrack AudioTrackList/removetrack_event Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? TextTrackList/removetrack_event Support in all current engines. Firefox31+Safari7+Chrome33+ Opera20+Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android4.4+Samsung Internet?Opera Android20+ VideoTrackList/removetrack_event Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | removetrack
|
The audioTracks and videoTracks attributes allow scripts to select which track
should play, but it is also possible to select specific tracks declaratively, by specifying
particular tracks in the fragment of the
URL of the media resource. The format of the fragment depends on the MIME type of the
media resource. [RFC2046] [URL]
A media element can have a group of associated text tracks, known as the media element's list of text tracks. The text tracks are sorted as follows:
The text tracks corresponding to track
element children of the media element, in tree order.
Any text tracks added using the addTextTrack() method, in the order they were added,
oldest first.
Any media-resource-specific text tracks (text tracks corresponding to data in the media resource), in the order defined by the media resource's format specification.
A text track consists of:
This decides how the track is handled by the user agent. The kind is represented by a string. The possible strings are:
subtitles
captions
descriptions
chapters
The kind of track can change dynamically, in the case of
a text track corresponding to a track element.
This is a human-readable string intended to identify the track for the user.
The label of a track can change dynamically, in the
case of a text track corresponding to a track element.
When a text track label is the empty string, the user agent should automatically generate an appropriate label from the text track's other properties (e.g. the kind of text track and the text track's language) for use in its user interface. This automatically-generated label is not exposed in the API.
This is a string extracted from the media resource specifically for in-band metadata tracks to enable such tracks to be dispatched to different scripts in the document.
Other than for in-band metadata text tracks, the in-band metadata track dispatch type is the empty string. How this value is populated for different media formats is described in steps to expose a media-resource-specific text track.
This is a string (a BCP 47 language tag) representing the language of the text track's cues. [BCP47]
The language of a text track can change dynamically,
in the case of a text track corresponding to a track element.
One of the following:
Indicates that the text track's cues have not been obtained.
Indicates that the text track is loading and there have been no fatal errors encountered so far. Further cues might still be added to the track by the parser.
Indicates that the text track has been loaded with no fatal errors.
Indicates that the text track was enabled, but when the user agent attempted to obtain it, this failed in some way (e.g., URL could not be parsed, network error, unknown text track format). Some or all of the cues are likely missing and will not be obtained.
The readiness state of a text track changes dynamically as the track is obtained.
One of the following:
Indicates that the text track is not active. Other than for the purposes of exposing the track in the DOM, the user agent is ignoring the text track. No cues are active, no events are fired, and the user agent will not attempt to obtain the track's cues.
Indicates that the text track is active, but that the user agent is not actively displaying the cues. If no attempt has yet been made to obtain the track's cues, the user agent will perform such an attempt momentarily. The user agent is maintaining a list of which cues are active, and events are being fired accordingly.
Indicates that the text track is active. If no attempt has yet been made to obtain the
track's cues, the user agent will perform such an attempt momentarily. The user agent is
maintaining a list of which cues are active, and events are being fired accordingly. In
addition, for text tracks whose kind is subtitles or captions, the cues are being overlaid on the video
as appropriate; for text tracks whose kind is descriptions, the user agent is making the
cues available to the user in a non-visual fashion; and for text tracks whose kind is chapters, the user agent is making available to
the user a mechanism by which the user can navigate to any point in the media
resource by selecting a cue.
The list of cues of a text track can change dynamically, either because the text track has not yet been loaded or is still loading, or due to DOM manipulation.
Each text track has a corresponding TextTrack object.
Each media element has a list of pending text tracks, which must initially be empty, a blocked-on-parser flag, which must initially be false, and a did-perform-automatic-track-selection flag, which must also initially be false.
Whenever a track element's parent node changes, the user agent must remove the
corresponding text track from any list of pending text tracks that it is
in.
Whenever a text track's text track readiness state changes to either loaded or failed to load, the user agent must remove it from any list of pending text tracks that it is in.
When a media element is created by an HTML parser or XML parser, the user agent must set the element's blocked-on-parser flag to true. When a media element is popped off the stack of open elements of an HTML parser or XML parser, the user agent must honor user preferences for automatic text track selection, populate the list of pending text tracks, and set the element's blocked-on-parser flag to false.
Whenever a text track that is in a media element's list of text tracks has its text track mode change value, the user agent must run the following steps for the media element:
If the media element's pending text track change notification flag is set, return.
Set the media element's pending text track change notification flag.
Queue a media element task given the media element to run these steps:
Unset the media element's pending text track change notification flag.
Fire an event named change at the media element's textTracks attribute's TextTrackList
object.
If the media element's show poster flag is not set, run the time marches on steps.
The task source for the tasks listed in this section is the DOM manipulation task source.
Each text track cue consists of:
An arbitrary string.
The time, in seconds and fractions of a second, that describes the beginning of the range of the media data to which the cue applies.
The time, in seconds and fractions of a second, that describes the end of the range of the media data to which the cue applies, or positive Infinity for an unbounded text track cue.
A boolean indicating whether playback of the media resource is to pause when the end of the range to which the cue applies is reached.
Additional fields, as needed for the format, including the actual data of the cue. For example, WebVTT has a text track cue writing direction and so forth. [WEBVTT]
Each text track cue has a corresponding TextTrackCue object (or more
specifically, an object that inherits from TextTrackCue — for example, WebVTT
cues use the VTTCue interface). A text track cue's in-memory
representation can be dynamically changed through this TextTrackCue API.
[WEBVTT]
A text track cue is associated with rules for updating the text track
rendering, as defined by the specification for the specific kind of text track
cue. These rules are used specifically when the object representing the cue is added to a
TextTrack object using the addCue()
method.
In addition, each text track cue has two pieces of dynamic information:
This flag must be initially unset. The flag is used to ensure events are fired appropriately when the cue becomes active or inactive, and to make sure the right cues are rendered.
The user agent must synchronously unset this flag whenever the text track cue is
removed from its text track's text track list of cues; whenever the
text track itself is removed from its media element's list of
text tracks or has its text track mode changed to disabled; and whenever the media element's readyState is changed back to HAVE_NOTHING. When the flag is unset in this way for one
or more cues in text tracks that were showing prior to the relevant incident, the user agent must, after having unset
the flag for all the affected cues, apply the rules for updating the text track
rendering of those text tracks. For example, for text tracks based on WebVTT, the rules for updating the display
of WebVTT text tracks. [WEBVTT]
This is used as part of the rendering model, to keep cues in a consistent position. It must initially be empty. Whenever the text track cue active flag is unset, the user agent must empty the text track cue display state.
The text track cues of a media element's text tracks are ordered relative to each other in the text track cue order, which is determined as follows: first group the cues by their text track, with the groups being sorted in the same order as their text tracks appear in the media element's list of text tracks; then, within each group, cues must be sorted by their start time, earliest first; then, any cues with the same start time must be sorted by their end time, latest first; and finally, any cues with identical end times must be sorted in the order they were last added to their respective text track list of cues, oldest first (so e.g. for cues from a WebVTT file, that would initially be the order in which the cues were listed in the file). [WEBVTT]
Rules for processing and rendering such data are defined by the relevant specifications, e.g. the specification of the video format if the media resource is a video. Details for some legacy formats can be found in Sourcing In-band Media Resource Tracks from Media Containers into HTML. [INBAND]
When a track element is created, it must be associated with a new text
track (with its value set as defined below) and its corresponding new
TextTrack object.
The text track kind is determined from the state of the element's kind attribute according to the following table; for a state given
in a cell of the first column, the kind is the string given
in the second column:
| State | String |
|---|---|
| Subtitles | subtitles
|
| Captions | captions
|
| Descriptions | descriptions
|
| Chapters metadata | chapters
|
| Metadata | metadata
|
The text track label is the element's track label.
The text track language is the element's track language, if any, or the empty string otherwise.
As the kind, label,
and srclang attributes are set, changed, or removed, the
text track must update accordingly, as per the definitions above.
The text track readiness state is initially not loaded, and the text track mode is initially disabled.
The text track list of cues is initially empty. It is dynamically modified when the referenced file is parsed. Associated with the list are the rules for updating the text track rendering appropriate for the format in question; for WebVTT, this is the rules for updating the display of WebVTT text tracks. [WEBVTT]
When a track element's parent element changes and the new parent is a media
element, then the user agent must add the track element's corresponding
text track to the media element's list of text tracks, and
then queue a media element task given the media element to fire an event named addtrack at the media element's textTracks attribute's TextTrackList object,
using TrackEvent, with the track attribute
initialized to the text track's TextTrack object.
When a track element's parent element changes and the old parent was a media
element, then the user agent must remove the track element's corresponding
text track from the media element's list of text tracks,
and then queue a media element task given the media element to fire an event named removetrack at the media element's textTracks attribute's TextTrackList object,
using TrackEvent, with the track attribute
initialized to the text track's TextTrack object.
When a text track corresponding to a track element is added to a
media element's list of text tracks, the user agent must queue a
media element task given the media element to run the following steps for the
media element:
If the element's blocked-on-parser flag is true, then return.
If the element's did-perform-automatic-track-selection flag is true, then return.
Honor user preferences for automatic text track selection for this element.
When a text track corresponding to a track element experiences any of
the following circumstances, the user agent must start the track processing
model for that text track and its track element:
track element is created.track element's parent element changes and the new parent is a media
element.Whenever a track element has its src attribute
set, changed, or removed, the user agent must immediately empty the element's text
track's text track list of cues. (This also causes the algorithm above to stop
adding cues from the resource being obtained using the previously given URL, if any.)
How a specific format's text track cues are to be interpreted for the purposes of processing by an HTML user agent is defined by that format. In the absence of such a specification, this section provides some constraints within which implementations can attempt to consistently expose such formats.
To support the text track model of HTML, each unit of timed data is converted to a text track cue. Where the mapping of the format's features to the aspects of a text track cue as defined in this specification are not defined, implementations must ensure that the mapping is consistent with the definitions of the aspects of a text track cue as defined above, as well as with the following constraints:
Should be set to the empty string if the format has no obvious analogue to a per-cue identifier.
Should be set to false.
Support in all current engines.
A TextTrackList object represents a dynamically updating list of text tracks in a given order.
The textTracks attribute of media elements must return a TextTrackList object representing the
TextTrack objects of the text tracks in the
media element's list of text tracks, in the same order as in the
list of text tracks.
Support in all current engines.
The supported property indices of a TextTrackList object at any
instant are the numbers from zero to the number of text tracks in
the list represented by the TextTrackList object minus one, if any. If there are no
text tracks in the list, there are no supported property
indices.
To determine the value of an indexed property of a
TextTrackList object for a given index index, the user agent must return
the indexth text track in the list represented by the
TextTrackList object.
The getTrackById(id) method must
return the first TextTrack in the TextTrackList object whose id IDL attribute would return a value equal to the value of the
id argument. When no tracks match the given argument, the method must return null.
Support in all current engines.
On setting, if the new value isn't equal to what the attribute would currently return, the new value must be processed as follows:
disabled"Set the text track mode of the text track that the
TextTrack object represents to the text track disabled mode.
Set the text track mode of the text track that the
TextTrack object represents to the mode.
showing"Set the text track mode of the text track that the
TextTrack object represents to the text track showing mode.
A text track cue's active flag was set when the script started if its text track cue active flag was set the last time the event loop reached step 1.
Support in all current engines.
A TextTrackCueList object represents a dynamically updating list of text track cues in a given order.
Support in all current engines.
The supported property indices of a TextTrackCueList object at any
instant are the numbers from zero to the number of cues in the
list represented by the TextTrackCueList object minus one, if any. If there are no
cues in the list, there are no supported property
indices.
To determine the value of an indexed property for a
given index index, the user agent must return the indexth text track
cue in the list represented by the TextTrackCueList object.
Support in all current engines.
The getCueById(id) method, when
called with an argument other than the empty string, must return the first text track
cue in the list represented by the TextTrackCueList object whose text
track cue identifier is id, if any, or null otherwise. If the argument is the
empty string, then the method must return null.
Support in all current engines.
Support in all current engines.
The track
attribute, on getting, must return the TextTrack object of the text
track in whose list of cues the text
track cue that the TextTrackCue object represents finds itself, if any; or
null otherwise.
Support in all current engines.
The id
attribute, on getting, must return the text track cue identifier of the text
track cue that the TextTrackCue object represents. On setting, the text
track cue identifier must be set to the new value.
Support in all current engines.
The startTime attribute, on getting, must return the
text track cue start time of the text track cue that the
TextTrackCue object represents, in seconds. On setting, the text track cue
start time must be set to the new value, interpreted in seconds; then, if the
TextTrackCue object's text track cue is in a text track's
list of cues, and that text track is in
a media element's list of text tracks, and the media
element's show poster flag is not set, then run the time marches on steps for that media element.
Support in all current engines.
The endTime attribute, on getting, must return the
text track cue end time of the text track cue that the
TextTrackCue object represents, in seconds or positive Infinity. On setting, if the
new value is negative Infinity or a Not-a-Number (NaN) value, then throw a TypeError
exception. Otherwise, the text track cue end time must be set to the new value.
Then, if the TextTrackCue object's text track cue is in a text
track's list of cues, and that text
track is in a media element's list of text tracks, and the
media element's show poster flag is not set, then run the time marches on steps for that media element.
Support in all current engines.
The pauseOnExit attribute, on getting, must return
true if the text track cue pause-on-exit flag of the text track cue that
the TextTrackCue object represents is set; or false otherwise. On setting, the
text track cue pause-on-exit flag must be set if the new value is true, and must be
unset otherwise.
The following are the event handlers that (and their corresponding event handler event types) that must
be supported, as event handler IDL attributes, by all objects implementing the
TextTrackList interface:
| Event handler | Event handler event type |
|---|---|
onchange | change
|
onaddtrack | addtrack
|
onremovetrack | removetrack
|
The following are the event handlers that (and their corresponding event handler event types) that must
be supported, as event handler IDL attributes, by all objects implementing the
TextTrack interface:
| Event handler | Event handler event type |
|---|---|
oncuechange Support in all current engines. Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | cuechange
|
The following are the event handlers (and their corresponding event handler event types) that must
be supported, as event handler IDL attributes, by all objects implementing the
TextTrackCue interface:
| Event handler | Event handler event type |
|---|---|
onenter Support in all current engines. Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | enter
|
onexit Support in all current engines. Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | exit
|
This section is non-normative.
Text tracks can be used for storing data relating to the media data, for interactive or augmented views.
For example, a page showing a sports broadcast could include information about the current score. Suppose a robotics competition was being streamed live. The image could be overlaid with the scores, as follows:
In order to make the score display render correctly whenever the user seeks to an arbitrary point in the video, the metadata text track cues need to be as long as is appropriate for the score. For example, in the frame above, there would be maybe one cue that lasts the length of the match that gives the match number, one cue that lasts until the blue alliance's score changes, and one cue that lasts until the red alliance's score changes. If the video is just a stream of the live event, the time in the bottom right would presumably be automatically derived from the current video time, rather than based on a cue. However, if the video was just the highlights, then that might be given in cues also.
The following shows what fragments of this could look like in a WebVTT file:
WEBVTT ... 05:10:00.000 --> 05:12:15.000 matchtype:qual matchnumber:37 ... 05:11:02.251 --> 05:11:17.198 red:78 05:11:03.672 --> 05:11:54.198 blue:66 05:11:17.198 --> 05:11:25.912 red:80 05:11:25.912 --> 05:11:26.522 red:83 05:11:26.522 --> 05:11:26.982 red:86 05:11:26.982 --> 05:11:27.499 red:89 ...
The key here is to notice that the information is given in cues that span the length of time to which the relevant event applies. If, instead, the scores were given as zero-length (or very brief, nearly zero-length) cues when the score changes, for example saying "red+2" at 05:11:17.198, "red+3" at 05:11:25.912, etc, problems arise: primarily, seeking is much harder to implement, as the script has to walk the entire list of cues to make sure that no notifications have been missed; but also, if the cues are short it's possible the script will never see that they are active unless it listens to them specifically.
When using cues in this manner, authors are encouraged to use the cuechange event to update the current annotations. (In
particular, using the timeupdate event would be less
appropriate as it would require doing work even when the cues haven't changed, and, more
importantly, would introduce a higher latency between when the metadata cues become active and
when the display is updated, since timeupdate events
are rate-limited.)
Other specifications or formats that need a URL to identify the return values of
the AudioTrack kind or
VideoTrack kind IDL attributes, or identify
the kind of text track, must use the
about:html-kind URL.
Even when the attribute is absent, however, user agents may provide controls to affect playback
of the media resource (e.g. play, pause, seeking, track selection, and volume controls), but such
features should not interfere with the page's normal rendering. For example, such features could
be exposed in the media element's context menu, platform media keys, or a remote
control. The user agent may implement this simply by exposing a user interface to the user as described above (as if the controls attribute was present).
If the user agent exposes a user interface to
the user by displaying controls over the media element, then the user agent
should suppress any user interaction events while the user agent is interacting with this
interface. (For example, if the user clicks on a video's playback control, mousedown events and so forth would not simultaneously be fired at
elements on the page.)
Where possible (specifically, for starting, stopping, pausing, and unpausing playback, for seeking, for changing the rate of playback, for fast-forwarding or rewinding, for listing, enabling, and disabling text tracks, and for muting or changing the volume of the audio), user interface features exposed by the user agent must be implemented in terms of the DOM API described above, so that, e.g., all the same events fire.
Features such as fast-forward or rewind must be implemented by only changing the playbackRate attribute (and not the defaultPlaybackRate
attribute).
Seeking must be implemented in terms of seeking to the requested position in the media element's media timeline. For media resources where seeking to an arbitrary position would be slow, user agents are encouraged to use the approximate-for-speed flag when seeking in response to the user manipulating an approximate position interface such as a seek bar.
Support in all current engines.
The controls IDL attribute must reflect the
content attribute of the same name.
Whenever either of the values that would be returned by the volume and muted IDL
attributes change, the user agent must queue a media element task given the
media element to fire an event named volumechange at the media element. Then, if
the media element is not allowed to play, the user agent must run the
internal pause steps for the media element.
The muted
content attribute on media elements is a boolean
attribute that controls the default state of the audio output of the media
resource, potentially overriding user preferences.
Support in all current engines.
The defaultMuted IDL attribute must reflect
the muted content attribute.
Support in all current engines.
Objects implementing the TimeRanges interface
represent a list of ranges (periods) of time.
These methods must throw "IndexSizeError" DOMExceptions
if called with an index argument greater than or equal to the number of ranges
represented by the object.
In other words, the ranges in such an object are ordered, don't overlap, and don't touch (adjacent ranges are folded into one bigger range). A range can be empty (referencing just a single moment in time), e.g. to indicate that only one frame is currently buffered in the case that the user agent has discarded the entire media resource except for the current frame, when a media element is paused.
Ranges in a TimeRanges object must be inclusive.
The timelines used by the objects returned by the buffered, seekable, and
played IDL attributes of media
elements must be that element's media timeline.
TrackEvent interfaceSupport in all current engines.
The track
attribute must return the value it was initialized to. It represents the context information for
the event.
This section is non-normative.
The following events fire on media elements as part of the processing model described above:
| Event name | Interface | Fired when... | Preconditions |
|---|---|---|---|
loadstart
HTMLMediaElement/loadstart_event Support in all current engines. Firefox6+Safari4+Chrome3+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| The user agent begins looking for media data, as part of the resource selection algorithm. | networkState equals NETWORK_LOADING
|
progress
HTMLMediaElement/progress_event Support in all current engines. Firefox6+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| The user agent is fetching media data. | networkState equals NETWORK_LOADING
|
suspend
HTMLMediaElement/suspend_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The user agent is intentionally not currently fetching media data. | networkState equals NETWORK_IDLE
|
abort
Support in all current engines. Firefox9+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| The user agent stops fetching the media data before it is completely downloaded, but not due to an error. | error is an object with the code MEDIA_ERR_ABORTED. networkState equals either NETWORK_EMPTY or NETWORK_IDLE, depending on when the download was aborted.
|
error
Support in all current engines. Firefox6+Safari3.1+Chrome3+ Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Event
| An error occurs while fetching the media data or the type of the resource is not a supported media format. | error is an object with the code MEDIA_ERR_NETWORK or higher. networkState equals either NETWORK_EMPTY or NETWORK_IDLE, depending on when the download was aborted.
|
emptied
HTMLMediaElement/emptied_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| A media element whose networkState
was previously not in the NETWORK_EMPTY state has
just switched to that state (either because of a fatal error during load that's about to be
reported, or because the load() method was invoked while
the resource selection algorithm was already
running).
| networkState is NETWORK_EMPTY; all the IDL attributes are in their
initial states.
|
stalled
HTMLMediaElement/stalled_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The user agent is trying to fetch media data, but data is unexpectedly not forthcoming. | networkState is NETWORK_LOADING.
|
loadedmetadata
HTMLMediaElement/loadedmetadata_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The user agent has just determined the duration and dimensions of the media resource and the text tracks are ready. | readyState is newly equal to HAVE_METADATA or greater for the first time.
|
loadeddata
HTMLMediaElement/loadeddata_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The user agent can render the media data at the current playback position for the first time. | readyState newly increased to HAVE_CURRENT_DATA or greater for the first time.
|
canplay
HTMLMediaElement/canplay_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The user agent can resume playback of the media data, but estimates that if playback were to be started now, the media resource could not be rendered at the current playback rate up to its end without having to stop for further buffering of content. | readyState newly increased to HAVE_FUTURE_DATA or greater.
|
canplaythrough
HTMLMediaElement/canplaythrough_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The user agent estimates that if playback were to be started now, the media resource could be rendered at the current playback rate all the way to its end without having to stop for further buffering. | readyState is newly equal to HAVE_ENOUGH_DATA.
|
playing
HTMLMediaElement/playing_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| Playback is ready to start after having been paused or delayed due to lack of media data. | readyState is newly greater than or equal to
HAVE_FUTURE_DATA and paused is false, or paused is newly false and readyState is greater than or equal to HAVE_FUTURE_DATA. Even if this event fires, the
element might still not be potentially playing, e.g. if the element is
paused for user interaction or paused for in-band content.
|
waiting
HTMLMediaElement/waiting_event Support in all current engines. Firefox6+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | Event
| Playback has stopped because the next frame is not available, but the user agent expects that frame to become available in due course. | readyState is less than or equal to HAVE_CURRENT_DATA, and paused is false. Either seeking is true, or the current playback position
is not contained in any of the ranges in buffered. It
is possible for playback to stop for other reasons without paused being false, but those reasons do not fire this event
(and when those situations resolve, a separate playing
event is not fired either): e.g., playback has ended, or
playback stopped due to errors, or the element has paused for user
interaction or paused for in-band content.
|
seeking
HTMLMediaElement/seeking_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The seeking IDL attribute changed to true, and the user agent has started seeking to a new position.
| |
seeked
Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The seeking IDL attribute changed to false after the current playback position was changed.
| |
ended
Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| Playback has stopped because the end of the media resource was reached. | currentTime equals the end of the media
resource; ended is true.
|
durationchange
HTMLMediaElement/durationchange_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The duration attribute has just been updated.
| |
timeupdate
HTMLMediaElement/timeupdate_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The current playback position changed as part of normal playback or in an especially interesting way, for example discontinuously. | |
play
Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The element is no longer paused. Fired after the play()
method has returned, or when the autoplay attribute
has caused playback to begin.
| paused is newly false.
|
pause
Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| The element has been paused. Fired after the pause()
method has returned.
| paused is newly true.
|
ratechange
HTMLMediaElement/ratechange_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | Event
| Either the defaultPlaybackRate or the
playbackRate attribute has just been updated.
| |
resize
| Event
| One or both of the videoWidth and videoHeight attributes have just been updated.
| Media element is a video element; readyState is not HAVE_NOTHING
|
volumechange
HTMLMediaElement/volumechange_event Support in all current engines. Firefox6+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | Event
| Either the volume attribute or the muted attribute has changed. Fired after the relevant
attribute's setter has returned.
|
The following event fires on source elements:
| Event name | Interface | Fired when... |
|---|---|---|
error
| Event
| An error occurs while fetching the media data or the type of the resource is not a supported media format. |
The following events fire on AudioTrackList, VideoTrackList, and
TextTrackList objects:
| Event name | Interface | Fired when... |
|---|---|---|
change
Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? Support in all current engines. Firefox31+Safari7+Chrome33+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android4.4+Samsung Internet?Opera Android? Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| One or more tracks in the track list have been enabled or disabled. |
addtrack
Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? Support in all current engines. Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | TrackEvent
| A track has been added to the track list. |
removetrack
AudioTrackList/removetrack_event Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? TextTrackList/removetrack_event Support in all current engines. Firefox31+Safari7+Chrome33+ Opera20+Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android4.4+Samsung Internet?Opera Android20+ VideoTrackList/removetrack_event Support in all current engines. Firefox🔰 33+Safari7+Chrome🔰 37+ Opera?Edge🔰 79+ Edge (Legacy)NoInternet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | TrackEvent
| A track has been removed from the track list. |
The following event fires on TextTrack objects and track elements:
| Event name | Interface | Fired when... |
|---|---|---|
cuechange
HTMLTrackElement/cuechange_event Support in all current engines. Firefox68+Safari10+Chrome32+ Opera19+Edge79+ Edge (Legacy)14+Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android4.4.3+Samsung Internet?Opera Android19+ Support in all current engines. Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| One or more cues in the track have become active or stopped being active. |
The following events fire on track elements:
| Event name | Interface | Fired when... |
|---|---|---|
error
| Event
| An error occurs while fetching the track data or the type of the resource is not supported text track format. |
load
| Event
| A track data has been fetched and successfully processed. |
The following events fire on TextTrackCue objects:
| Event name | Interface | Fired when... |
|---|---|---|
enter
Support in all current engines. Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| The cue has become active. |
exit
Support in all current engines. Firefox31+Safari6+Chrome23+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS7+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| The cue has stopped being active. |
The main security and privacy implications of the video and audio
elements come from the ability to embed media cross-origin. There are two directions that threats
can flow: from hostile content to a victim page, and from a hostile page to victim content.
If a victim page embeds hostile content, the threat is that the content might contain scripted
code that attempts to interact with the Document that embeds the content. To avoid
this, user agents must ensure that there is no access from the content to the embedding page. In
the case of media content that uses DOM concepts, the embedded content must be treated as if it
was in its own unrelated top-level traversable.
If a hostile page embeds victim content, the threat is that the embedding page could obtain
information from the content that it would not otherwise have access to. The API does expose some
information: the existence of the media, its type, its duration, its size, and the performance
characteristics of its host. Such information is already potentially problematic, but in practice
the same information can more or less be obtained using the img element, and so it
has been deemed acceptable.
However, significantly more sensitive information could be obtained if the user agent further
exposes metadata within the content, such as subtitles. That information is therefore only exposed
if the video resource uses CORS. The crossorigin
attribute allows authors to enable CORS. [FETCH]
This section is non-normative.
Playing audio and video resources on small devices such as set-top boxes or mobile phones is
often constrained by limited hardware resources in the device. For example, a device might only
support three simultaneous videos. For this reason, it is a good practice to release resources
held by media elements when they are done playing, either by
being very careful about removing all references to the element and allowing it to be garbage
collected, or, even better, by setting the element's src
attribute to an empty string. In cases where srcObject
was set, instead set the srcObject to null.
Similarly, when the playback rate is not exactly 1.0, hardware, software, or format limitations can cause video frames to be dropped and audio to be choppy or muted.
This section is non-normative.
How accurately various aspects of the media element API are implemented is considered a quality-of-implementation issue.
For example, when implementing the buffered attribute,
how precise an implementation reports the ranges that have been buffered depends on how carefully
the user agent inspects the data. Since the API reports ranges as times, but the data is obtained
in byte streams, a user agent receiving a variable-bitrate stream might only be able to determine
precise times by actually decoding all of the data. User agents aren't required to do this,
however; they can instead return estimates (e.g. based on the average bitrate seen so far) which
get revised as more information becomes available.
As a general rule, user agents are urged to be conservative rather than optimistic. For example, it would be bad to report that everything had been buffered when it had not.
Another quality-of-implementation issue would be playing a video backwards when the codec is designed only for forward playback (e.g. there aren't many key frames, and they are far apart, and the intervening frames only have deltas from the previous frame). User agents could do a poor job, e.g. only showing key frames; however, better implementations would do more work and thus do a better job, e.g. actually decoding parts of the video forwards, storing the complete frames, and then playing the frames backwards.
Similarly, while implementations are allowed to drop buffered data at any time (there is no requirement that a user agent keep all the media data obtained for the lifetime of the media element), it is again a quality of implementation issue: user agents with sufficient resources to keep all the data around are encouraged to do so, as this allows for a better user experience. For example, if the user is watching a live stream, a user agent could allow the user only to view the live video; however, a better user agent would buffer everything and allow the user to seek through the earlier material, pause it, play it forwards and backwards, etc.
When a media element that is paused is removed from a document and not reinserted before the next time the event loop reaches step 1, implementations that are resource constrained are encouraged to take that opportunity to release all hardware resources (like video planes, networking resources, and data buffers) used by the media element. (User agents still have to keep track of the playback position and so forth, though, in case playback is later restarted.)
map elementSupport in all current engines.
Support in all current engines.
name — Name of image map to reference from the usemap attribute
The map element, in conjunction with an img element and any
area element descendants, defines an image map. The element
represents its children.
The IDL attribute name must reflect the content attribute of the
same name.
area elementSupport in all current engines.
Support in all current engines.
map element ancestor.alt — Replacement text for use when images are not available
coords — Coordinates for the shape to be created in an image map
shape — The kind of shape to be created in an image map
href — Address of the hyperlink
target — Navigable for hyperlink navigation
download — Whether to download the resource instead of navigating to it, and its filename if so
ping — URLs to ping
rel — Relationship between the location in the document containing the hyperlink and the destination resource
referrerpolicy — Referrer policy for fetches initiated by the element
href attribute: for authors; for implementers.The area element represents either a hyperlink with some text and a
corresponding area on an image map, or a dead area on an image map.
An area element with a parent node must have a map element
ancestor.
If the area element has no href
attribute, then the area represented by the element cannot be selected, and the alt attribute must be omitted.
In both cases, the shape and coords attributes specify the area.
The shape attribute is
an enumerated attribute with the following keywords and states:
| Keyword | Conforming | State | Brief description |
|---|---|---|---|
circle
| Circle state | Designates a circle, using exactly three integers in the coords attribute.
| |
circ
| No | ||
default
| Default state | This area is the whole image. (The coords
attribute is not used.)
| |
poly
| Polygon state | Designates a polygon, using at-least six integers in the coords attribute.
| |
polygon
| No | ||
rect
| Rectangle state | Designates a rectangle, using exactly four integers in the coords attribute.
| |
rectangle
| No |
The attribute's missing value default and invalid value default are both the rectangle state.
When user agents allow users to follow hyperlinks or
download hyperlinks created using the
area element, the href, target, download, and ping attributes decide how the link is followed. The rel attribute may be used to indicate to the user the likely
nature of the target resource before the user follows the link.
The target, download, ping,
rel, and referrerpolicy attributes must be omitted if the
href attribute is not present.
If the itemprop attribute is specified on an
area element, then the href attribute must
also be specified.
Support in all current engines.
The IDL attributes alt, coords, shape, target, download, ping, and rel, each must reflect the respective content
attributes of the same name.
Support in all current engines.
The IDL attribute relList must reflect the rel content attribute.
HTMLAreaElement/referrerPolicy
Support in all current engines.
The IDL attribute referrerPolicy must reflect the referrerpolicy content attribute, limited to
only known values.
An image, in the form of an img element, may be associated with an image map (in
the form of a map element) by specifying a usemap attribute on the img element. The
usemap attribute, if specified, must be a valid
hash-name reference to a map element.
If an img element has a usemap
attribute specified, user agents must process it as follows:
Parse the attribute's value using the rules for parsing a hash-name reference
to a map element, with the element as the context node. This will return either an
element (the map) or null.
If that returned null, then return. The image is not associated with an image map after all.
Otherwise, the user agent must collect all the area elements that are
descendants of the map. Let those be the areas.
Having obtained the list of area elements that form the image map (the areas), interactive user agents must process the list in one of two ways.
If the user agent intends to show the text that the img element represents, then
it must use the following steps.
Remove all the area elements in areas that have no href attribute.
Remove all the area elements in areas that have no alt attribute, or whose alt
attribute's value is the empty string, if there is another area element in
areas with the same value in the href attribute and with a non-empty alt attribute.
Each remaining area element in areas represents a
hyperlink. Those hyperlinks should all be made available to the user in a manner
associated with the text of the img.
In this context, user agents may represent area and img elements
with no specified alt attributes, or whose alt
attributes are the empty string or some other non-visible text, in an
implementation-defined fashion intended to indicate the lack of suitable
author-provided text.
If the user agent intends to show the image and allow interaction with the image to select
hyperlinks, then the image must be associated with a set of layered shapes, taken from the
area elements in areas, in reverse tree order (so the last
specified area element in the map is the bottom-most shape, and
the first element in the map, in tree order, is the top-most shape).
Each area element in areas must be processed as follows to
obtain a shape to layer onto the image:
Find the state that the element's shape attribute
represents.
Use the rules for parsing a list of floating-point numbers to parse the
element's coords attribute, if it is present, and let the
result be the coords list. If the attribute is absent, let the coords list
be the empty list.
If the number of items in the coords list is less than the minimum number
given for the area element's current state, as per the following table, then the
shape is empty; return.
| State | Minimum number of items |
|---|---|
| Circle state | 3 |
| Default state | 0 |
| Polygon state | 6 |
| Rectangle state | 4 |
Check for excess items in the coords list as per the entry in the
following list corresponding to the shape attribute's
state:
If the shape attribute represents the rectangle state, and the first number in the list is
numerically greater than the third number in the list, then swap those two numbers around.
If the shape attribute represents the rectangle state, and the second number in the list is
numerically greater than the fourth number in the list, then swap those two numbers around.
If the shape attribute represents the circle state, and the third number in the list is less than
or equal to zero, then the shape is empty; return.
Now, the shape represented by the element is the one described for the entry in the list
below corresponding to the state of the shape attribute:
Let x be the first number in coords, y be the second number, and r be the third number.
The shape is a circle whose center is x CSS pixels from the left edge of the image and y CSS pixels from the top edge of the image, and whose radius is r CSS pixels.
The shape is a rectangle that exactly covers the entire image.
Let xi be the (2i)th entry in coords, and yi be the (2i+1)th entry in coords (the first entry in coords being the one with index 0).
Let the coordinates be (xi, yi), interpreted in CSS pixels measured from the top left of the image, for all integer values of i from 0 to (N/2)-1, where N is the number of items in coords.
The shape is a polygon whose vertices are given by the coordinates, and whose interior is established using the even-odd rule. [GRAPHICS]
Let x1 be the first number in coords, y1 be the second number, x2 be the third number, and y2 be the fourth number.
The shape is a rectangle whose top-left corner is given by the coordinate (x1, y1) and whose bottom right corner is given by the coordinate (x2, y2), those coordinates being interpreted as CSS pixels from the top left corner of the image.
For historical reasons, the coordinates must be interpreted relative to the
displayed image after any stretching caused by the CSS 'width' and
'height' properties (or, for non-CSS browsers, the image element's width and height attributes — CSS browsers map
those attributes to the aforementioned CSS properties).
Pointing device interaction with an image associated with a set of layered shapes per the above
algorithm must result in the relevant user interaction events being first fired to the top-most
shape covering the point that the pointing device indicated, if any, or to the image element
itself, if there is no shape covering that point. User agents may also allow individual
area elements representing hyperlinks to be selected
and activated (e.g. using a keyboard).
Image maps are live; if the DOM is mutated, then the user agent must act as if it had rerun the algorithms for image maps.
HTML/HTML5/HTML5_Parser#Inline_SVG_and_MathML_support
Support in all current engines.
The MathML math element falls into the embedded content,
phrasing content, flow content, and palpable content
categories for the purposes of the content models in this specification.
When the MathML annotation-xml element contains elements from the
HTML namespace, such elements must all be flow content.
When the MathML token elements (mi, mo, mn, ms, and mtext) are descendants of HTML elements, they may contain
phrasing content elements from the HTML namespace.
User agents must handle text other than inter-element whitespace found in MathML
elements whose content models do not allow straight text by pretending for the purposes of MathML
content models, layout, and rendering that the text is actually wrapped in a MathML
mtext element. (Such text is not, however, conforming.)
User agents must act as if any MathML element whose contents does not match the element's
content model was replaced, for the purposes of MathML layout and rendering, by a MathML
merror element containing some appropriate error message.
The semantics of MathML elements are defined by MathML and other applicable specifications. [MATHML]
HTML/HTML5/HTML5_Parser#Inline_SVG_and_MathML_support
Support in all current engines.
The SVG svg element falls into the embedded content,
phrasing content, flow content, and palpable content
categories for the purposes of the content models in this specification.
When the SVG foreignObject element contains elements from the
HTML namespace, such elements must all be flow content.
The content model for the SVG title element inside HTML
documents is phrasing content. (This further constrains the requirements given
in SVG 2.)
The semantics of SVG elements are defined by SVG 2 and other applicable specifications. [SVG]
The specified dimensions given may differ from the dimensions specified in the resource itself, since the resource may have a resolution that differs from the CSS pixel resolution. (On screens, CSS pixels have a resolution of 96ppi, but in general the CSS pixel resolution depends on the reading distance.) If both attributes are specified, then one of the following statements must be true:
The target ratio is the ratio of the natural width to the
natural height in the resource. The specified width and specified
height are the values of the width and height attributes respectively.
The two attributes must be omitted if the resource in question does not have both a natural width and a natural height.
If the two attributes are both 0, it indicates that the element is not intended for the user (e.g. it might be a part of a service to count page views).
User agent requirements: User agents are expected to use these attributes as hints for the rendering.
Support in all current engines.
Support in all current engines.
The width and height IDL attributes on the iframe,
embed, object, source, and video elements must
reflect the respective content attributes of the same name.
table elementSupport in all current engines.
Support in all current engines.
caption element, followed by zero or more
colgroup elements, followed optionally by a thead element, followed by
either zero or more tbody elements or one or more tr elements, followed
optionally by a tfoot element, optionally intermixed with one or more
script-supporting elements.The table element represents data with more than one dimension, in
the form of a table.
The table element takes part in the table
model. Tables have rows, columns, and cells given by their descendants. The rows and
columns form a grid; a table's cells must completely cover that grid without overlap.
Authors are encouraged to provide information describing how to interpret complex tables. Guidance on how to provide such information is given below.
Tables must not be used as layout aids. Historically, some web authors have misused tables in HTML as a way to control their page layout. This usage is non-conforming, because tools attempting to extract tabular data from such documents would obtain very confusing results. In particular, users of accessibility tools like screen readers are likely to find it very difficult to navigate pages with tables used for layout.
Tables can be complicated to understand and navigate. To help users with this, user agents should clearly delineate cells in a table from each other, unless the user agent has classified the table as a (non-conforming) layout table.
User agents, especially those that do table analysis on arbitrary content, are encouraged to find heuristics to determine which tables actually contain data and which are merely being used for layout. This specification does not define a precise heuristic, but the following are suggested as possible indicators:
| Feature | Indication |
|---|---|
The use of the role attribute with the value presentation
| Probably a layout table |
The use of the non-conforming border attribute with the non-conforming value 0
| Probably a layout table |
The use of the non-conforming cellspacing and
cellpadding attributes with the value 0
| Probably a layout table |
The use of caption, thead, or th elements
| Probably a non-layout table |
The use of the headers and scope attributes
| Probably a non-layout table |
The use of the non-conforming border attribute with a value other than 0
| Probably a non-layout table |
| Explicit visible borders set using CSS | Probably a non-layout table |
The use of the summary attribute
| Not a good indicator (both layout and non-layout tables have historically been given this attribute) |
If a table element has a (non-conforming) summary attribute, and the user agent has not classified the
table as a layout table, the user agent may report the contents of that attribute to the user.
For tables that consist of more than just a grid of cells with headers in the first row and headers in the first column, and for any table in general where the reader might have difficulty understanding the content, authors should include explanatory information introducing the table. This information is useful for all users, but is especially useful for users who cannot see the table, e.g. users of screen readers.
Such explanatory information should introduce the purpose of the table, outline its basic cell structure, highlight any trends or patterns, and generally teach the user how to use the table.
For instance, the following table:
| Negative | Characteristic | Positive |
|---|---|---|
| Sad | Mood | Happy |
| Failing | Grade | Passing |
...might benefit from a description explaining the way the table is laid out, something like "Characteristics are given in the second column, with the negative side in the left column and the positive side in the right column".
There are a variety of ways to include this information, such as:
captioncaption, in a details elementfigurefigure's figcaptionAuthors may also use other techniques, or combinations of the above techniques, as appropriate.
The best option, of course, rather than writing a description explaining the way the table is laid out, is to adjust the table such that no explanation is needed.
Good table design is key to making tables more readable and usable.
In visual media, providing column and row borders and alternating row backgrounds can be very effective to make complicated tables more readable.
For tables with large volumes of numeric content, using monospaced fonts can help users see patterns, especially in situations where a user agent does not render the borders. (Unfortunately, for historical reasons, not rendering borders on tables is a common default.)
In speech media, table cells can be distinguished by reporting the corresponding headers before reading the cell's contents, and by allowing users to navigate the table in a grid fashion, rather than serializing the entire contents of the table in source order.
Authors are encouraged to use CSS to achieve these effects.
User agents are encouraged to render tables using these techniques whenever the page does not use CSS and the table is not classified as a layout table.
caption elementSupport in all current engines.
Support in all current engines.
table element.table elements.caption element's end tag can be omitted if
the caption element is not immediately followed by ASCII whitespace or a
comment.The caption element represents the title of the table
that is its parent, if it has a parent and that is a table element.
The caption element takes part in the table model.
When a table element is the only content in a figure element other
than the figcaption, the caption element should be omitted in favor of
the figcaption.
A caption can introduce context for a table, making it significantly easier to understand.
colgroup elementSupport in all current engines.
Support in all current engines.
table element, after any
caption elements and before any thead,
tbody, tfoot, and tr
elements.span attribute is present: Nothing.span attribute is absent: Zero or more col and template elements.colgroup element's start tag can be
omitted if the first thing inside the colgroup element is a col element,
and if the element is not immediately preceded by another colgroup element whose
end tag has been omitted. (It can't be omitted if the element
is empty.)colgroup element's end tag can be omitted
if the colgroup element is not immediately followed by ASCII whitespace
or a comment.span — Number of columns spanned by the element
The colgroup element represents a group of one or more columns in the table that is its parent, if it has a
parent and that is a table element.
The colgroup element and its span
attribute take part in the table model.
The span
IDL attribute must reflect the content attribute of the same name. It is
clamped to the range [1, 1000], and its default value is 1.
col elementSupport in all current engines.
colgroup element that doesn't have
a span attribute.span — Number of columns spanned by the element
HTMLTableColElement, as defined for colgroup elements.If a col element has a parent and that is a colgroup element that
itself has a parent that is a table element, then the col element
represents one or more columns in the column group represented by that colgroup.
The col element and its span attribute take
part in the table model.
tbody elementSupport in all current engines.
Support in all current engines.
table element, after any
caption, colgroup, and
thead elements, but only if there are no
tr elements that are children of the
table element.tr and script-supporting elements.tbody element's start tag can be omitted
if the first thing inside the tbody element is a tr element, and if the
element is not immediately preceded by a tbody, thead, or
tfoot element whose end tag has been omitted. (It
can't be omitted if the element is empty.)tbody element's end tag can be omitted if
the tbody element is immediately followed by a tbody or
tfoot element, or if there is no more content in the parent element.The
HTMLTableSectionElement interface is also used for thead and
tfoot elements.
The tbody element represents a block of rows that consist of a
body of data for the parent table element, if the tbody element has a
parent and it is a table.
The tbody element takes part in the table model.
thead elementSupport in all current engines.
table element, after any
caption, and colgroup
elements and before any tbody, tfoot, and
tr elements, but only if there are no other
thead elements that are children of the
table element.tr and script-supporting elements.thead element's end tag can be omitted if
the thead element is immediately followed by a tbody or
tfoot element.HTMLTableSectionElement, as defined for tbody elements.The thead element represents the block of rows that consist of
the column labels (headers) and any ancillary non-header cells for the parent table
element, if the thead element has a parent and it is a table.
The thead element takes part in the table model.
tfoot elementSupport in all current engines.
table element, after any
caption, colgroup, thead,
tbody, and tr elements, but only if there
are no other tfoot elements that are children of the
table element.tr and script-supporting elements.tfoot element's end tag can be omitted if
there is no more content in the parent element.HTMLTableSectionElement, as defined for tbody elements.The tfoot element represents the block of rows that consist of
the column summaries (footers) for the parent table element, if the
tfoot element has a parent and it is a table.
The tfoot element takes part in the table
model.
tr elementSupport in all current engines.
Support in all current engines.
thead element.tbody element.tfoot element.table element, after any
caption, colgroup, and thead
elements, but only if there are no tbody elements that
are children of the table element.td, th, and script-supporting elements.tr element's end tag can be omitted if the
tr element is immediately followed by another tr element, or if there is
no more content in the parent element.The tr element represents a row of
cells in a table.
The tr element takes part in the table model.
td elementSupport in all current engines.
Support in all current engines.
tr element.td element's end tag can be omitted if the
td element is immediately followed by a td or th element,
or if there is no more content in the parent element.colspan — Number of columns that the cell is to span
rowspan — Number of rows that the cell is to span
headers — The header cells for this cell
The
HTMLTableCellElement interface is also used for th elements.
The td element represents a data cell in a table.
The td element and its colspan, rowspan, and headers
attributes take part in the table model.
User agents, especially in non-visual environments or where displaying the table as a 2D grid
is impractical, may give the user context for the cell when rendering the contents of a cell; for
instance, giving its position in the table model, or listing the cell's header cells
(as determined by the algorithm for assigning header cells). When a cell's header
cells are being listed, user agents may use the value of abbr
attributes on those header cells, if any, instead of the contents of the header cells
themselves.
th elementSupport in all current engines.
tr element.header, footer,
sectioning content, or heading content descendants.th element's end tag can be omitted if the
th element is immediately followed by a td or th element,
or if there is no more content in the parent element.colspan — Number of columns that the cell is to span
rowspan — Number of rows that the cell is to span
headers — The header cells for this cell
scope — Specifies which cells the header cell applies to
abbr — Alternative label to use for the header cell when referencing the cell in other contexts
HTMLTableCellElement, as defined for td elements.The th element represents a header cell in a table.
The scope attribute is an enumerated attribute
with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
row
| row | The header cell applies to some of the subsequent cells in the same row(s). |
col
| column | The header cell applies to some of the subsequent cells in the same column(s). |
rowgroup
| row group | The header cell applies to all the remaining cells in the row group. |
colgroup
| column group | The header cell applies to all the remaining cells in the column group. |
A th element's scope attribute must not be in
the row group state if the element is not anchored in
a row group, nor in the column group state if the element is not anchored in a
column group.
The th element and its colspan, rowspan, headers, and
scope attributes take part in the table model.
td and th elementsThese attributes give the number of columns and rows respectively that the cell is to span. These attributes must not be used to overlap cells, as described in the description of the table model.
A th element with ID id is
said to be directly targeted by all td and th elements in the
same table that have headers attributes whose values include as one of their tokens
the ID id. A th element A is said to be targeted by a th or td element
B if either A is directly targeted by B or if there exists an element C that is itself
targeted by the element B and A is directly
targeted by C.
A th element must not be targeted by itself.
The colspan, rowspan, and headers
attributes take part in the table model.
The abbr IDL
attribute must reflect the content attribute of the same name.
It is possible, in certain error cases, for two cells to occupy the same slot.
Row groups cannot overlap each other. Similarly, column groups cannot overlap each other.
A cell cannot cover slots that are from two or more row groups. It is, however, possible for a cell to be in multiple column groups. All the slots that form part of one cell are part of zero or one row groups and zero or more column groups.
In addition to cells, columns, rows, row groups, and column
groups, tables can have a caption element
associated with them. This gives the table a heading, or legend.
A table model error is an error with the data represented by table
elements and their descendants. Documents must not have table model errors.
To determine which elements correspond to which slots in a table associated with a table element, to determine the
dimensions of the table (xwidth and yheight), and to determine if there are any table model errors, user agents must use the following algorithm:
Let xwidth be zero.
Let yheight be zero.
Let pending tfoot elements be a list of tfoot
elements, initially empty.
Let the table be the table represented
by the table element. The xwidth and yheight variables give the table's
dimensions. The table is initially empty.
If the table element has no children elements, then return the
table (which will be empty).
Associate the first caption element child of the table element with
the table. If there are no such children, then it has no associated
caption element.
Let the current element be the first element child of the
table element.
While the current element is not one of the following elements, advance the current element to the next
child of the table:
If the current element is a colgroup, follow these
substeps:
Column groups: Process the current element according to the appropriate case below:
col element childrenFollow these steps:
Let xstart have the value of xwidth.
Let the current column be the first col element child
of the colgroup element.
Columns: If the current column col element has
a span attribute, then parse its value using the
rules for parsing non-negative integers.
If the result of parsing the value is not an error or zero, then let span be that value.
Otherwise, if the col element has no span attribute, or if trying to parse the attribute's value
resulted in an error or zero, then let span be 1.
If span is greater than 1000, let it be 1000 instead.
Increase xwidth by span.
Let the last span columns in
the table correspond to the current column
col element.
If current column is not the last col element child of
the colgroup element, then let the current column be the
next col element child of the colgroup element, and return to
the step labeled columns.
Let all the last columns in the
table from x=xstart to
x=xwidth-1 form a new column group, anchored at the slot (xstart, 0), with width xwidth-xstart, corresponding to the colgroup element.
col element childrenIf the colgroup element has a span
attribute, then parse its value using the rules for parsing non-negative
integers.
If the result of parsing the value is not an error or zero, then let span be that value.
Otherwise, if the colgroup element has no span attribute, or if trying to parse the attribute's
value resulted in an error or zero, then let span be 1.
If span is greater than 1000, let it be 1000 instead.
Increase xwidth by span.
Let the last span columns in
the table form a new column
group, anchored at the slot (xwidth-span, 0), with width span, corresponding to the colgroup element.
While the current element is not one of the following elements, advance the current element to the
next child of the table:
If the current element is a colgroup element, jump to the
step labeled column groups above.
Let ycurrent be zero.
Let the list of downward-growing cells be an empty list.
Rows: While the current element is not one of the following
elements, advance the current
element to the next child of the table:
If the current element is a tr, then run the algorithm
for processing rows, advance the current element to the next child of the table, and return to the
step labeled rows.
Run the algorithm for ending a row group.
If the current element is a tfoot, then add that element to
the list of pending tfoot elements, advance the current element to the next
child of the table, and return to the step labeled rows.
The current element is either a thead or a
tbody.
Run the algorithm for processing row groups.
Return to the step labeled rows.
End: For each tfoot element in the list of pending
tfoot elements, in tree order, run the algorithm for processing row
groups.
If there exists a row or column in the table containing only slots that do not have a cell anchored to them, then this is a table model error.
Return the table.
When the algorithms above require the user agent to run the algorithm for growing downward-growing cells, the user agent must, for each {cell, cellx, width} tuple in the list of downward-growing cells, if any, extend the cell cell so that it also covers the slots with coordinates (x, ycurrent), where cellx ≤ x < cellx+width.
A cell is said to be an empty cell if it contains no elements and its child text content, if any, consists only of ASCII whitespace.
This section is non-normative.
The following shows how one might mark up the bottom part of table 45 of the Smithsonian physical tables, Volume 71:
This table could look like this:
| Grade. | Yield Point. | Ultimate tensile strength | Per cent elong. 50.8 mm or 2 in. | Per cent reduct. area. | |
|---|---|---|---|---|---|
| kg/mm2 | lb/in2 | ||||
| Hard | 0.45 ultimate | 56.2 | 80,000 | 15 | 20 |
| Medium | 0.45 ultimate | 49.2 | 70,000 | 18 | 25 |
| Soft | 0.45 ultimate | 42.2 | 60,000 | 22 | 30 |
The following shows how one might mark up the gross margin table on page 46 of Apple, Inc's 10-K filing for fiscal year 2008:
This table could look like this:
| 2008 | 2007 | 2006 | |
|---|---|---|---|
| Net sales | $ 32,479 | $ 24,006 | $ 19,315 |
| Cost of sales | 21,334 | 15,852 | 13,717 |
| Gross margin | $ 11,145 | $ 8,154 | $ 5,598 |
| Gross margin percentage | 34.3% | 34.0% | 29.0% |
The following shows how one might mark up the operating expenses table from lower on the same page of that document:
This table could look like this:
| 2008 | 2007 | 2006 | |
|---|---|---|---|
| Research and development | $ 1,109 | $ 782 | $ 712 |
| Percentage of net sales | 3.4% | 3.3% | 3.7% |
| Selling, general, and administrative | $ 3,761 | $ 2,963 | $ 2,433 |
| Percentage of net sales | 11.6% | 12.3% | 12.6% |
Support in all current engines.
This section is non-normative.
A form is a component of a web page that has form controls, such as text, buttons, checkboxes, range, or color picker controls. A user can interact with such a form, providing data that can then be sent to the server for further processing (e.g. returning the results of a search or calculation). No client-side scripting is needed in many cases, though an API is available so that scripts can augment the user experience or use forms for purposes other than submitting data to a server.
Writing a form consists of several steps, which can be performed in any order: writing the user interface, implementing the server-side processing, and configuring the user interface to communicate with the server.
This section is non-normative.
For the purposes of this brief introduction, we will create a pizza ordering form.
Any form starts with a form element, inside which are placed the controls. Most
controls are represented by the input element, which by default provides a text
control. To label a control, the label element is used; the label text and the
control itself go inside the label element. Each part of a form is considered a
paragraph, and is typically separated from other parts using p elements.
Putting this together, here is how one might ask for the customer's name:
To let the user select the size of the pizza, we can use a set of radio buttons. Radio buttons
also use the input element, this time with a type attribute with the value radio. To make the radio buttons work as a group, they are
given a common name using the name attribute. To group a batch
of controls together, such as, in this case, the radio buttons, one can use the
fieldset element. The title of such a group of controls is given by the first element
in the fieldset, which has to be a legend element.
To pick toppings, we can use checkboxes. These use the input element with a type attribute with the value checkbox:
The pizzeria for which this form is being written is always making mistakes, so it needs a way
to contact the customer. For this purpose, we can use form controls specifically for telephone
numbers (input elements with their type
attribute set to tel) and email addresses
(input elements with their type attribute set
to email):
We can use an input element with its type
attribute set to time to ask for a delivery time. Many
of these form controls have attributes to control exactly what values can be specified; in this
case, three attributes of particular interest are min, max, and step. These set the
minimum time, the maximum time, and the interval between allowed values (in seconds). This
pizzeria only delivers between 11am and 9pm, and doesn't promise anything better than 15 minute
increments, which we can mark up as follows:
The textarea element can be used to provide a multiline text control. In this
instance, we are going to use it to provide a space for the customer to give delivery
instructions:
Finally, to make the form submittable we use the button element:
This section is non-normative.
The exact details for writing a server-side processor are out of scope for this specification.
For the purposes of this introduction, we will assume that the script at https://pizza.example.com/order.cgi is configured to accept submissions using the
application/x-www-form-urlencoded format,
expecting the following parameters sent in an HTTP POST body:
custnamecusttelcustemailsizesmall, medium, or largetoppingbacon, cheese, onion, and mushroomdeliverycommentsThis section is non-normative.
Form submissions are exposed to servers in a variety of ways, most commonly as HTTP GET or POST
requests. To specify the exact method used, the method
attribute is specified on the form element. This doesn't specify how the form data is
encoded, though; to specify that, you use the enctype
attribute. You also have to specify the URL of the service that will handle the
submitted data, using the action attribute.
For each form control you want submitted, you then have to give a name that will be used to
refer to the data in the submission. We already specified the name for the group of radio buttons;
the same attribute (name) also specifies the submission name.
Radio buttons can be distinguished from each other in the submission by giving them different
values, using the value attribute.
Multiple controls can have the same name; for example, here we give all the checkboxes the same
name, and the server distinguishes which checkbox was checked by seeing which values are submitted
with that name — like the radio buttons, they are also given unique values with the value attribute.
Given the settings in the previous section, this all becomes:
For example, if the customer entered "Denise Lawrence" as their name, "555-321-8642" as their telephone number, did not specify an email address, asked for a medium-sized pizza, selected the Extra Cheese and Mushroom toppings, entered a delivery time of 7pm, and left the delivery instructions text control blank, the user agent would submit the following to the online web service:
Support in all current engines.
This section is non-normative.
Forms can be annotated in such a way that the user agent will check the user's input before the form is submitted. The server still has to verify the input is valid (since hostile users can easily bypass the form validation), but it allows the user to avoid the wait incurred by having the server be the sole checker of the user's input.
The simplest annotation is the required attribute,
which can be specified on input elements to indicate that the form is not to be
submitted until a value is given. By adding this attribute to the customer name, pizza size, and
delivery time fields, we allow the user agent to notify the user when the user submits the form
without filling in those fields:
It is also possible to limit the length of the input, using the maxlength attribute. By adding this to the textarea
element, we can limit users to 1000 characters, preventing them from writing huge essays to the
busy delivery drivers instead of staying focused and to the point:
This section is non-normative.
Some browsers attempt to aid the user by automatically filling form controls rather than having the user reenter their information each time. For example, a field asking for the user's telephone number can be automatically filled with the user's phone number.
To help the user agent with this, the autocomplete
attribute can be used to describe the field's purpose. In the case of this form, we have three
fields that can be usefully annotated in this way: the information about who the pizza is to be
delivered to. Adding this information looks like this:
This section is non-normative.
Some devices, in particular those with virtual keyboards can provide the user with multiple input modalities. For example, when typing in a credit card number the user may wish to only see keys for digits 0-9, while when typing in their name they may wish to see a form field that by default capitalizes each word.
Using the inputmode attribute we can select appropriate
input modalities:
This section is non-normative.
The type, autocomplete, and inputmode attributes can seem confusingly similar. For instance,
in all three cases, the string "email" is a valid value. This section
attempts to illustrate the difference between the three attributes and provides advice suggesting
how to use them.
The type attribute on input elements decides
what kind of control the user agent will use to expose the field. Choosing between different
values of this attribute is the same choice as choosing whether to use an input
element, a textarea element, a select element, etc.
The autocomplete attribute, in contrast, describes
what the value that the user will enter actually represents. Choosing between different values of
this attribute is the same choice as choosing what the label for the element will be.
First, consider telephone numbers. If a page is asking for a telephone number from the user,
the right form control to use is <input type=tel>.
However, which autocomplete value to use depends on
which phone number the page is asking for, whether they expect a telephone number in the
international format or just the local format, and so forth.
For example, a page that forms part of a checkout process on an e-commerce site for a customer buying a gift to be shipped to a friend might need both the buyer's telephone number (in case of payment issues) and the friend's telephone number (in case of delivery issues). If the site expects international phone numbers (with the country code prefix), this could thus look like this:
But if the site only supports British customers and recipients, it might instead look like this
(notice the use of tel-national rather than
tel):
Now, consider a person's preferred languages. The right autocomplete value is language. However, there could be a number of
different form controls used for the purpose: a text control (<input type=text>), a drop-down list (<select>), radio buttons (<input
type=radio>), etc. It only depends on what kind of interface is desired.
Finally, consider names. If a page just wants one name from the user, then the relevant control
is <input type=text>. If the page is asking for the
user's full name, then the relevant autocomplete value
is name.
In this example, the "section-*" keywords in
the autocomplete attributes' values tell the user agent
that the two fields expect different names. Without them, the user agent could
automatically fill the second field with the value given in the first field when the user gave a
value to the first field.
Separate from the choices regarding type and autocomplete, the inputmode attribute decides what kind of input modality (e.g.,
virtual keyboard) to use, when the control is a text control.
Consider credit card numbers. The appropriate input type is not <input type=number>, as explained below; it is instead <input type=text>. To encourage the user agent to use a
numeric input modality anyway (e.g., a virtual keyboard displaying only digits), the page would
use
This section is non-normative.
In this pizza delivery example, the times are specified in the format "HH:MM": two digits for the hour, in 24-hour format, and two digits for the time. (Seconds could also be specified, though they are not necessary in this example.)
In some locales, however, times are often expressed differently when presented to users. For example, in the United States, it is still common to use the 12-hour clock with an am/pm indicator, as in "2pm". In France, it is common to separate the hours from the minutes using an "h" character, as in "14h00".
Similar issues exist with dates, with the added complication that even the order of the components is not always consistent — for example, in Cyprus the first of February 2003 would typically be written "1/2/03", while that same date in Japan would typically be written as "2003年02月01日" — and even with numbers, where locales differ, for example, in what punctuation is used as the decimal separator and the thousands separator.
It is therefore important to distinguish the time, date, and number formats used in HTML and in form submissions, which are always the formats defined in this specification (and based on the well-established ISO 8601 standard for computer-readable date and time formats), from the time, date, and number formats presented to the user by the browser and accepted as input from the user by the browser.
The format used "on the wire", i.e., in HTML markup and in form submissions, is intended to be computer-readable and consistent irrespective of the user's locale. Dates, for instance, are always written in the format "YYYY-MM-DD", as in "2003-02-01". While some users might see this format, others might see it as "01.02.2003" or "February 1, 2003".
The time, date, or number given by the page in the wire format is then translated to the user's preferred presentation (based on user preferences or on the locale of the page itself), before being displayed to the user. Similarly, after the user inputs a time, date, or number using their preferred format, the user agent converts it back to the wire format before putting it in the DOM or submitting it.
This allows scripts in pages and on servers to process times, dates, and numbers in a consistent manner without needing to support dozens of different formats, while still supporting the users' needs.
Mostly for historical reasons, elements in this section fall into several overlapping (but subtly different) categories in addition to the usual ones like flow content, phrasing content, and interactive content.
The form-associated elements fall into several subcategories:
Denotes elements that are listed in the form.elements and fieldset.elements APIs. These elements also
have a form content attribute, and a matching form IDL attribute, that allow authors to specify an explicit
form owner.
Denotes elements that can be used for constructing the entry list when a
form element is submitted.
Denotes elements that can be affected when a form element is reset.
Denotes elements that inherit the autocapitalize
and autocorrect attributes from their form
owner.
form elementSupport in all current engines.
Support in all current engines.
form element descendants.accept-charset — Character encodings to use for form submission
action — URL to use for form submission
autocomplete — Default setting for autofill feature for controls in the form
enctype — Entry list encoding type to use for form submission
method — Variant to use for form submission
name — Name of form to use in the document.forms API
novalidate — Bypass form control validation for form submission
target — Navigable for form submission
relThe form element represents a hyperlink that can be
manipulated through a collection of form-associated
elements, some of which can represent editable values that can be submitted to a server for
processing.
The autocomplete attribute is an enumerated
attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
on
| on | Form controls will have their autofill field name set to "on" by default.
|
off
| off | Form controls will have their autofill field name set to "off" by default.
|
The attribute's missing value default and invalid value default are both the on state.
The action, enctype,
method, novalidate,
and target attributes are attributes for form
submission.
rel's supported
tokens are the keywords defined in HTML link types which are
allowed on form elements, impact the processing model, and are supported by the user
agent. The possible supported tokens are noreferrer, noopener, and opener. rel's supported tokens must only include the tokens from this
list that the user agent implements the processing model for.
The autocomplete IDL attribute must reflect
the content attribute of the same name, limited to only known values.
Support in all current engines.
The name and
rel IDL attributes
must reflect the content attribute of the same name.
Support in all current engines.
The relList
IDL attribute must reflect the rel content
attribute.
The supported property indices at any instant are the indices supported by the
object returned by the elements attribute at that
instant.
To determine the value of an indexed property for a
form element, the user agent must return the value returned by the item method on the elements collection, when invoked with the given index as its
argument.
The supported property names consist of the names obtained from the following algorithm, in the order obtained from this algorithm:
Let sourced names be an initially empty ordered list of tuples consisting of a string, an element, a source, where the source is either id, name, or past, and, if the source is past, an age.
For each listed element candidate
whose form owner is the form element, with the exception of any
input elements whose type attribute is in the
Image Button state:
If candidate has an id attribute, add
an entry to sourced names with that id
attribute's value as the string, candidate as the element, and id as
the source.
If candidate has a name attribute,
add an entry to sourced names with that name attribute's value as the string, candidate
as the element, and name as the source.
For each img element candidate whose form owner is the
form element:
If candidate has an id attribute, add
an entry to sourced names with that id
attribute's value as the string, candidate as the element, and id as
the source.
If candidate has a name attribute,
add an entry to sourced names with that name attribute's value as the string, candidate
as the element, and name as the source.
For each entry past entry in the past names map, add an entry to sourced names with the past entry's name as the string, past entry's element as the element, past as the source, and the length of time past entry has been in the past names map as the age.
Sort sourced names by tree order of the element entry of each tuple, sorting entries with the same element by putting entries whose source is id first, then entries whose source is name, and finally entries whose source is past, and sorting entries with the same element and source by their age, oldest first.
Remove any entries in sourced names that have the empty string as their name.
Remove any entries in sourced names that have the same name as an earlier entry in the map.
Return the list of names from sourced names, maintaining their relative order.
To determine the value of a named property name
for a form element, the user agent must run the following steps:
Let candidates be a live RadioNodeList object
containing all the listed elements, whose form
owner is the form element, that have either an id attribute or a name attribute equal
to name, with the exception of input elements whose type attribute is in the Image Button state, in tree order.
If candidates is empty, let candidates be a live
RadioNodeList object containing all the img elements, whose form
owner is the form element, that have either an id attribute or a name attribute
equal to name, in tree order.
If candidates is empty, name is the name of one of
the entries in the form element's past names map: return the object
associated with name in that map.
If candidates contains more than one node, return candidates.
Otherwise, candidates contains exactly one node. Add a mapping from
name to the node in candidates in the form
element's past names map, replacing the previous entry with the same name, if
any.
Return the node in candidates.
If an element listed in a form element's past names map changes
form owner, then its entries must be removed from that map.
If the reportValidity() method is invoked, the user agent
must interactively validate the constraints of the form element, and
return true if the constraint validation return a positive result, and false if it returned
a negative result.
label elementSupport in all current engines.
Support in all current engines.
label elements.for — Associate the label with form control
Except where otherwise specified by the following rules, a label element has no
labeled control.
Support in all current engines.
If the for attribute is not specified, but the
label element has a labelable element descendant,
then the first such descendant in tree order is the label element's
labeled control.
The label element's exact default presentation and behavior, in particular what
its activation behavior might be, if anything, should match the platform's label
behavior. The activation behavior of a label element for events targeted
at interactive content descendants of a label element, and any
descendants of those interactive content descendants, must be to do nothing.
Support in all current engines.
Labelable elements and all input elements
have a live NodeList object associated with them that represents the
list of label elements, in tree order, whose labeled
control is the element in question. The labels IDL attribute of labelable elements that are not form-associated custom elements, and the labels IDL attribute of input elements, on getting,
must return that NodeList object, and that same value must always be returned, unless
this element is an input element whose type
attribute is in the state, in which case it
must instead return null.
Support in all current engines.
Form-associated custom elements don't have
a labels IDL attribute. Instead, their
ElementInternals object has a labels IDL attribute. On getting, it must throw
a "NotSupportedError" DOMException if the target element is not a form-associated custom
element. Otherwise, it must return that NodeList object, and that same value
must always be returned.
input elementSupport in all current engines.
Support in all current engines.
type attribute is not in the Hidden state: Interactive content.type attribute is not in the Hidden state: Listed, labelable, submittable, resettable, and autocapitalize-and-autocorrect inheriting form-associated element.type attribute is in the Hidden state: Listed, submittable, resettable, and autocapitalize-and-autocorrect inheriting form-associated element.type attribute is not in the Hidden state: Palpable content.accept — Hint for expected file type in file upload controls
alpha — Allow the color's alpha component to be set
alt — Replacement text for use when images are not available
autocomplete — Hint for form autofill feature
checked — Whether the control is checked
colorspace — The color space of the serialized color
dirname — Name of form control to use for sending the element's directionality in form submission
disabled — Whether the form control is disabled
form — Associates the element with a form element
formaction — URL to use for form submission
formenctype — Entry list encoding type to use for form submission
formmethod — Variant to use for form submission
formnovalidate — Bypass form control validation for form submission
formtarget — Navigable for form submission
height — Vertical dimension
list — List of autocomplete options
max — Maximum value
maxlength — Maximum length of value
min — Minimum value
minlength — Minimum length of value
multiple — Whether to allow multiple values
name — Name of the element to use for form submission and in the form.elements API
pattern — Pattern to be matched by the form control's value
placeholder — User-visible label to be placed within the form control
popovertarget — Targets a popover element to toggle, show, or hide
popovertargetaction — Indicates whether a targeted popover element is to be toggled, shown, or hidden
readonly — Whether to allow the value to be edited by the user
required — Whether the control is required for form submission
size — Size of the control
src — Address of the resource
step — Granularity to be matched by the form control's value
type — Type of form control
value — Value of the form control
width — Horizontal dimension
title attribute has special semantics on this element: Description of pattern (when used with pattern attribute)
type attribute in the Hidden state: for authors; for implementers.type attribute in the Text state: for authors; for implementers.type attribute in the Search state: for authors; for implementers.type attribute in the Telephone state: for authors; for implementers.type attribute in the URL state: for authors; for implementers.type attribute in the Email state: for authors; for implementers.type attribute in the Password state: for authors; for implementers.type attribute in the Date state: for authors; for implementers.type attribute in the Month state: for authors; for implementers.type attribute in the Week state: for authors; for implementers.type attribute in the Time state: for authors; for implementers.type attribute in the Local Date and Time state: for authors; for implementers.type attribute in the Number state: for authors; for implementers.type attribute in the Range state: for authors; for implementers.type attribute in the Color state: for authors; for implementers.type attribute in the Checkbox state: for authors; for implementers.type attribute in the Radio Button state: for authors; for implementers.type attribute in the File Upload state: for authors; for implementers.type attribute in the Submit Button state: for authors; for implementers.type attribute in the Image Button state: for authors; for implementers.type attribute in the Reset Button state: for authors; for implementers.type attribute in the Button state: for authors; for implementers.The input element represents a typed data field, usually with a form
control to allow the user to edit the data.
The type attribute
controls the data type (and associated control) of the element. It is an enumerated
attribute with the following keywords and states:
| Keyword | State | Data type | Control type |
|---|---|---|---|
hidden
| An arbitrary string | n/a | |
text
| Text | Text with no line breaks | A text control |
search
| Search | Text with no line breaks | Search control |
tel
| Telephone | Text with no line breaks | A text control |
url
| URL | An absolute URL | A text control |
email
| An email address or list of email addresses | A text control | |
password
| Password | Text with no line breaks (sensitive information) | A text control that obscures data entry |
date
| Date | A date (year, month, day) with no time zone | A date control |
month
| Month | A date consisting of a year and a month with no time zone | A month control |
week
| Week | A date consisting of a week-year number and a week number with no time zone | A week control |
time
| Time | A time (hour, minute, seconds, fractional seconds) with no time zone | A time control |
datetime-local
| Local Date and Time | A date and time (year, month, day, hour, minute, second, fraction of a second) with no time zone | A date and time control |
number
| Number | A numerical value | A text control or spinner control |
range
| Range | A numerical value, with the extra semantic that the exact value is not important | A slider control or similar |
color
| Color | An sRGB color with 8-bit red, green, and blue components | A color picker |
checkbox
| Checkbox | A set of zero or more values from a predefined list | A checkbox |
radio
| Radio Button | An enumerated value | A radio button |
file
| File Upload | Zero or more files each with a MIME type and optionally a filename | A label and a button |
submit
| Submit Button | An enumerated value, with the extra semantic that it must be the last value selected and initiates form submission | A button |
image
| Image Button | A coordinate, relative to a particular image's size, with the extra semantic that it must be the last value selected and initiates form submission | Either a clickable image, or a button |
reset
| Reset Button | n/a | A button |
button
| Button | n/a | A button |
The attribute's missing value default and invalid value default are both the Text state.
The following table is non-normative and summarizes which of those content attributes, IDL attributes, methods, and events apply to each state:
| Text, Search | Telephone, URL | Password | Date, Month, Week, Time | Local Date and Time | Number | Range | Color | Checkbox, Radio Button | File Upload | Submit Button | Image Button | Reset Button, Button | |||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Content attributes | |||||||||||||||
accept
| · | · | · | · | · | · | · | · | · | · | · | Yes | · | · | · |
alpha
| · | · | · | · | · | · | · | · | · | Yes | · | · | · | · | · |
alt
| · | · | · | · | · | · | · | · | · | · | · | · | · | Yes | · |
autocomplete
| Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · |
checked
| · | · | · | · | · | · | · | · | · | · | Yes | · | · | · | · |
colorspace
| · | · | · | · | · | · | · | · | · | Yes | · | · | · | · | · |
dirname
| Yes | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · | Yes | · | · |
formaction
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formenctype
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formmethod
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formnovalidate
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
formtarget
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | · |
height
| · | · | · | · | · | · | · | · | · | · | · | · | · | Yes | · |
list
| · | Yes | Yes | Yes | · | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · |
max
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
maxlength
| · | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · | · |
min
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
minlength
| · | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · | · |
multiple
| · | · | · | Yes | · | · | · | · | · | · | · | Yes | · | · | · |
pattern
| · | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · | · |
placeholder
| · | Yes | Yes | Yes | Yes | · | · | Yes | · | · | · | · | · | · | · |
popovertarget
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | Yes |
popovertargetaction
| · | · | · | · | · | · | · | · | · | · | · | · | Yes | Yes | Yes |
readonly
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · |
required
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | Yes | Yes | · | · | · |
size
| · | Yes | Yes | Yes | Yes | · | · | · | · | · | · | · | · | · | · |
src
| · | · | · | · | · | · | · | · | · | · | · | · | · | Yes | · |
step
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
width
| · | · | · | · | · | · | · | · | · | · | · | · | · | Yes | · |
| IDL attributes and methods | |||||||||||||||
checked
| · | · | · | · | · | · | · | · | · | · | Yes | · | · | · | · |
files
| · | · | · | · | · | · | · | · | · | · | · | Yes | · | · | · |
value
| default | value | value | value | value | value | value | value | value | value | default/on | filename | default | default | default |
valueAsDate
| · | · | · | · | · | Yes | · | · | · | · | · | · | · | · | · |
valueAsNumber
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
list
| · | Yes | Yes | Yes | · | Yes | Yes | Yes | Yes | Yes | · | · | · | · | · |
select()
| · | Yes | Yes | Yes† | Yes | Yes† | Yes† | Yes† | · | Yes† | · | Yes† | · | · | · |
selectionStart
| · | Yes | Yes | · | Yes | · | · | · | · | · | · | · | · | · | · |
selectionEnd
| · | Yes | Yes | · | Yes | · | · | · | · | · | · | · | · | · | · |
selectionDirection
| · | Yes | Yes | · | Yes | · | · | · | · | · | · | · | · | · | · |
setRangeText()
| · | Yes | Yes | · | Yes | · | · | · | · | · | · | · | · | · | · |
setSelectionRange()
| · | Yes | Yes | · | Yes | · | · | · | · | · | · | · | · | · | · |
stepDown()
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
stepUp()
| · | · | · | · | · | Yes | Yes | Yes | Yes | · | · | · | · | · | · |
| Events | |||||||||||||||
input event
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · |
change event
| · | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | · | · | · |
† If the control has no selectable text, the select() method results in a no-op, with no
"InvalidStateError" DOMException.
An input element's dirty value flag must be
set to true whenever the user interacts with the control in a way that changes the value. (It is also set to true when the value is programmatically
changed, as described in the definition of the value IDL
attribute.)
Each input element has a checkedness,
which is exposed by the checked IDL attribute.
Each input element has a boolean dirty checkedness flag. When it is true, the
element is said to have a dirty checkedness.
The dirty checkedness flag must be initially
set to false when the element is created, and must be set to true whenever the user interacts with
the control in a way that changes the checkedness.
Support in all current engines.
The reset algorithm for input
elements is to set its user validity,
dirty value flag, and
dirty checkedness flag
back to false, set the value of the element to the value
of the value content attribute, if there is one, or the
empty string otherwise, set the checkedness of the
element to true if the element has a checked content
attribute and false if it does not, empty the list of selected files, and then invoke the value
sanitization algorithm, if the type attribute's
current state defines one.
Each input element can be mutable. Except where
otherwise specified, an input element is always mutable. Similarly, except where otherwise specified, the user
agent should not allow the user to modify the element's value or checkedness.
When an input element is disabled, it is not mutable.
The cloning steps for input elements
given node, copy, and subtree are to propagate the value, dirty value flag,
checkedness, and dirty checkedness flag from node to
copy.
The activation behavior for input elements element, given
event, are these steps:
If element is not mutable and is not in the Checkbox state and is not in the Radio state, then return.
Run the popover target attribute activation behavior given element and event's target.
The legacy-pre-activation behavior for input elements are these
steps:
If this element's type attribute is in the Checkbox state, then set this element's checkedness to its opposite value (i.e. true if it is false,
false if it is true) and set this element's indeterminate IDL attribute to false.
If this element's type attribute is in the Radio Button state, then get a reference to the element in
this element's radio button group that has its checkedness set to true, if any, and then set this element's
checkedness to true.
The legacy-canceled-activation behavior for input elements are these
steps:
If the element's type attribute is in the Checkbox state, then set the element's checkedness and the element's indeterminate IDL attribute back to the values they had
before the legacy-pre-activation behavior was run.
If this element's type attribute is in the Radio Button state, then if the element to which a
reference was obtained in the legacy-pre-activation behavior, if any, is still in
what is now this element's radio button group, if it still has one, and if so,
setting that element's checkedness to true; or else, if
there was no such element, or that element is no longer in this element's radio button
group, or if this element no longer has a radio button group, setting this
element's checkedness to false.
When an input element is first created, the element's rendering and behavior must
be set to the rendering and behavior defined for the type
attribute's state, and the value sanitization algorithm, if one is defined for the
type attribute's state, must be invoked.
When an input element's type attribute
changes state, the user agent must run the following steps:
If the previous state of the element's type attribute
put the value IDL attribute in the value mode, and the element's value is not the empty string, and the new state of the element's
type attribute puts the value IDL attribute in either the default mode or the default/on mode, then set the element's value content attribute to the element's value.
Otherwise, if the previous state of the element's type attribute put the value
IDL attribute in any mode other than the value mode, and the
new state of the element's type attribute puts the value IDL attribute in the value mode, then set the value of the element to the value of the value content attribute, if there is one, or the empty string
otherwise, and then set the control's dirty value flag to
false.
Otherwise, if the previous state of the element's type attribute put the value IDL attribute in any mode other than the filename mode, and the new state of the element's type attribute puts the value IDL attribute in the filename mode, then set the value of the element to the empty string.
Update the element's rendering and behavior to the new state's.
Invoke the value sanitization algorithm, if one is defined for the type attribute's new state.
Let previouslySelectable be true if setRangeText() previously applied to the element, and false otherwise.
Let nowSelectable be true if setRangeText() now applies to the element, and false otherwise.
If previouslySelectable is false and nowSelectable is true, set the
element's text entry cursor position to the
beginning of the text control, and set its selection
direction to "none".
The name attribute represents the element's name.
The dirname attribute controls how the element's directionality is submitted.
The disabled attribute is used to make the control non-interactive and to prevent its value from being submitted.
The form attribute is used to explicitly associate the input element with its form owner.
The autocomplete attribute controls how the user agent provides autofill behavior.
HTMLInputElement#indeterminate
Support in all current engines.
The indeterminate IDL attribute must initially be set to
false. On getting, it must return the last value it was set to. On setting, it must be set to the
new value. It has no effect except for changing the appearance of checkbox controls.
Support in all current engines.
The accept,
alpha, alt, max, min, multiple, pattern, placeholder, required, size, src, and step IDL attributes must
reflect the respective content attributes of the same name. The dirName IDL attribute must
reflect the dirname content attribute. The readOnly IDL
attribute must reflect the readonly content
attribute. The defaultChecked IDL attribute must
reflect the checked content attribute. The
defaultValue IDL attribute must reflect
the value content attribute.
The colorSpace IDL attribute must reflect the
colorspace content attribute, limited to only
known values. The type IDL attribute must reflect the respective
content attribute of the same name, limited to only known values. The maxLength IDL attribute
must reflect the maxlength content
attribute, limited to only non-negative numbers. The minLength IDL
attribute must reflect the minlength
content attribute, limited to only non-negative numbers.
On setting, they must act as if they reflected the respective content attributes of the same name.
The willValidate, validity, and validationMessage IDL attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the
constraint validation API. The labels IDL
attribute provides a list of the element's labels. The select(), selectionStart, selectionEnd, selectionDirection, setRangeText(), and setSelectionRange() methods and IDL attributes
expose the element's text selection. The disabled,
form, and name IDL attributes
are part of the element's forms API.
type attributetype=hidden)Support in all current engines.
When an element's attribute is in the state, the rules in this section apply.
The element a value that is not intended to be examined or manipulated by the user.
Constraint validation: If an element's attribute is in the state, it is .
If the attribute is present and has a value that is an match for "", then the element's attribute must be omitted.
type=text) state and Search state (type=search)Support in all current engines.
Support in all current engines.
When an input element's type attribute is in
the Text state or the Search state, the rules in this section apply.
The input element represents a one line plain text edit control for
the element's value.
If the element is mutable, its value should be editable by the user. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the element's value.
If the element is mutable, the user agent should allow the user to change the writing direction of the element, setting it either to a left-to-right writing direction or a right-to-left writing direction. If the user does so, the user agent must then run the following steps:
Set the element's dir attribute to "ltr" if the user selected a left-to-right writing direction, and
"rtl" if the user selected a right-to-left writing
direction.
Queue an element task on the user interaction task source given
the element to fire an event named input at the element, with the bubbles and composed
attributes initialized to true.
The value attribute, if specified, must have a value that
contains no U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters.
The value sanitization algorithm is as follows: Strip newlines from the value.
type=tel)Support in all current engines.
When an input element's type attribute is in
the Telephone state, the rules in this section apply.
The input element represents a control for editing a telephone number
given in the element's value.
If the element is mutable, its value should be editable by the user. User agents may change the spacing and, with care, the punctuation of values that the user enters. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the element's value.
The value attribute, if specified, must have a value that
contains no U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters.
The value sanitization algorithm is as follows: Strip newlines from the value.
type=url)Support in all current engines.
When an input element's type attribute is in
the URL state, the rules in this section apply.
The input element represents a control for editing a single
absolute URL given in the element's value.
If the element is mutable, the user agent should allow the user to change the URL represented by its value. User agents may allow the user to set the value to a string that is not a valid absolute URL, but may also or instead automatically escape characters entered by the user so that the value is always a valid absolute URL (even if that isn't the actual value seen and edited by the user in the interface). User agents should allow the user to set the value to the empty string. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the value.
The value attribute, if specified and not empty, must
have a value that is a valid URL potentially surrounded by spaces that is also an
absolute URL.
The value sanitization algorithm is as follows: Strip newlines from the value, then strip leading and trailing ASCII whitespace from the value.
Constraint validation: While the value of the element is neither the empty string nor a valid absolute URL, the element is suffering from a type mismatch.
type=email)Support in all current engines.
When an input element's type attribute is in
the Email state, the rules in this section apply.
How the Email state operates depends on whether the
multiple attribute is specified or not.
multiple attribute is not specified on the
elementThe input element represents a control for editing an email
address given in the element's value.
If the element is mutable, the user agent should allow the user to change the email address represented by its value. User agents may allow the user to set the value to a string that is not a valid email address. The user agent should act in a manner consistent with expecting the user to provide a single email address. User agents should allow the user to set the value to the empty string. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the value. User agents may transform the value for display and editing; in particular, user agents should convert punycode in the domain labels of the value to IDN in the display and vice versa.
Constraint validation: While the user interface is representing input that the user agent cannot convert to punycode, the control is suffering from bad input.
The value attribute, if specified and not empty, must
have a value that is a single valid email address.
The value sanitization algorithm is as follows: Strip newlines from the value, then strip leading and trailing ASCII whitespace from the value.
Constraint validation: While the value of the element is neither the empty string nor a single valid email address, the element is suffering from a type mismatch.
multiple attribute is specified on
the elementThe input element represents a control for adding, removing, and
editing the email addresses given in the element's values.
If the element is mutable, the user agent should allow the user to add, remove, and edit the email addresses represented by its values. User agents may allow the user to set any individual value in the list of values to a string that is not a valid email address, but must not allow users to set any individual value to a string containing U+002C COMMA (,), U+000A LINE FEED (LF), or U+000D CARRIAGE RETURN (CR) characters. User agents should allow the user to remove all the addresses in the element's values. User agents may transform the values for display and editing; in particular, user agents should convert punycode in the domain labels of the value to IDN in the display and vice versa.
Constraint validation: While the user interface describes a situation where an individual value contains a U+002C COMMA (,) or is representing input that the user agent cannot convert to punycode, the control is suffering from bad input.
Whenever the user changes the element's values, the user agent must run the following steps:
Let latest values be a copy of the element's values.
Strip leading and trailing ASCII whitespace from each value in latest values.
Let the element's value be the result of concatenating all the values in latest values, separating each value from the next by a single U+002C COMMA character (,), maintaining the list's order.
The value attribute, if specified, must have a value
that is a valid email address list.
The value sanitization algorithm is as follows:
Split on commas the element's value, strip leading and trailing ASCII whitespace from each resulting token, if any, and let the element's values be the (possibly empty) resulting list of (possibly empty) tokens, maintaining the original order.
Let the element's value be the result of concatenating the element's values, separating each value from the next by a single U+002C COMMA character (,), maintaining the list's order.
Constraint validation: While the value of the element is not a valid email address list, the element is suffering from a type mismatch.
When the multiple attribute is set or removed, the
user agent must run the value sanitization algorithm.
A valid email address is a string that matches the email production of the following ABNF, the character set for which is Unicode.
This ABNF implements the extensions described in RFC 1123. [ABNF] [RFC5322]
[RFC1034] [RFC1123]
email = 1* ( atext / "." ) "@" label * ( "." label )
label = let-dig [ [ ldh-str ] let-dig ] ; limited to a length of 63 characters by RFC 1034 section 3.5
atext = < as defined in RFC 5322 section 3 .2 .3 >
let-dig = < as defined in RFC 1034 section 3 .5 >
ldh-str = < as defined in RFC 1034 section 3 .5 >
A valid email address list is a set of comma-separated tokens, where each token is itself a valid email address. To obtain the list of tokens from a valid email address list, an implementation must split the string on commas.
type=password)Support in all current engines.
When an input element's type attribute is in
the Password state, the rules in this section
apply.
The input element represents a one line plain text edit control for
the element's value. The user agent should obscure the value
so that people other than the user cannot see it.
If the element is mutable, its value should be editable by the user. User agents must not allow users to insert U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters into the value.
The value attribute, if specified, must have a value that
contains no U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters.
The value sanitization algorithm is as follows: Strip newlines from the value.
type=date)Support in all current engines.
When an input element's type attribute is in
the Date state, the rules in this section apply.
The input element represents a control for setting the element's
value to a string representing a specific date.
If the element is mutable, the user agent should allow the user to change the date represented by its value, as obtained by parsing a date from it. User agents must not allow the user to set the value to a non-empty string that is not a valid date string. If the user agent provides a user interface for selecting a date, then the value must be set to a valid date string representing the user's selection. User agents should allow the user to set the value to the empty string.
Constraint validation: While the user interface describes input that the user agent cannot convert to a valid date string, the control is suffering from bad input.
The value attribute, if specified and not empty, must
have a value that is a valid date string.
The value sanitization algorithm is as follows: If the value of the element is not a valid date string, then set it to the empty string instead.
The min attribute, if specified, must have a value that is
a valid date string. The max attribute, if
specified, must have a value that is a valid date string.
The step attribute is expressed in days. The step scale factor is 86,400,000
(which converts the days to milliseconds, as used in the other algorithms). The default step is 1 day.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest date for which the element would not suffer from a step mismatch.
The algorithm to convert a string to a
number, given a string input, is as follows: If parsing a date from input results in an
error, then return an error; otherwise, return the number of milliseconds elapsed from midnight
UTC on the morning of 1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0Z") to midnight UTC on the morning of the parsed date, ignoring leap seconds.
The algorithm to convert a number to a
string, given a number input, is as follows: Return a
valid date string that represents the date that, in
UTC, is current input milliseconds after midnight UTC on the morning of
1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0Z").
The algorithm to convert a string to a
Date object, given a string input, is as follows:
If parsing a date from input results
in an error, then return an error; otherwise, return a new
Date object representing midnight UTC on the morning of the parsed date.
The algorithm to convert a
Date object to a string, given a Date object input, is
as follows: Return a valid date string that represents the date current at the time represented by input in the UTC
time zone.
type=month)Support in all current engines.
When an input element's type attribute is in
the Month state, the rules in this section apply.
The input element represents a control for setting the element's
value to a string representing a specific month.
If the element is mutable, the user agent should allow the user to change the month represented by its value, as obtained by parsing a month from it. User agents must not allow the user to set the value to a non-empty string that is not a valid month string. If the user agent provides a user interface for selecting a month, then the value must be set to a valid month string representing the user's selection. User agents should allow the user to set the value to the empty string.
Constraint validation: While the user interface describes input that the user agent cannot convert to a valid month string, the control is suffering from bad input.
The value attribute, if specified and not empty, must
have a value that is a valid month string.
The value sanitization algorithm is as follows: If the value of the element is not a valid month string, then set it to the empty string instead.
The min attribute, if specified, must have a value that is
a valid month string. The max attribute, if
specified, must have a value that is a valid month string.
The step attribute is expressed in months. The step scale factor is 1 (there is no
conversion needed as the algorithms use months). The default step is 1 month.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest month for which the element would not suffer from a step mismatch.
The algorithm to convert a string to a number, given a string input, is as follows: If parsing a month from input results in an error, then return an error; otherwise, return the number of months between January 1970 and the parsed month.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid month string that represents the month that has input months between it and January 1970.
The algorithm to convert a string to a
Date object, given a string input, is as follows:
If parsing a month from input
results in an error, then return an error; otherwise, return a
new Date object representing midnight UTC on the morning of the first day of
the parsed month.
The algorithm to convert a
Date object to a string, given a Date object input, is
as follows: Return a valid month string that represents the month current at the time represented by input in the UTC
time zone.
type=week)When an input element's type attribute is in
the Week state, the rules in this section apply.
The input element represents a control for setting the element's
value to a string representing a specific week.
If the element is mutable, the user agent should allow the user to change the week represented by its value, as obtained by parsing a week from it. User agents must not allow the user to set the value to a non-empty string that is not a valid week string. If the user agent provides a user interface for selecting a week, then the value must be set to a valid week string representing the user's selection. User agents should allow the user to set the value to the empty string.
Constraint validation: While the user interface describes input that the user agent cannot convert to a valid week string, the control is suffering from bad input.
The value attribute, if specified and not empty, must
have a value that is a valid week string.
The value sanitization algorithm is as follows: If the value of the element is not a valid week string, then set it to the empty string instead.
The min attribute, if specified, must have a value that is
a valid week string. The max attribute, if
specified, must have a value that is a valid week string.
The step attribute is expressed in weeks. The step scale factor is 604,800,000
(which converts the weeks to milliseconds, as used in the other algorithms). The default step is 1 week. The default step base is −259,200,000 (the start
of week 1970-W01).
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest week for which the element would not suffer from a step mismatch.
The algorithm to convert a string to a
number, given a string input, is as follows: If parsing a week string from input results in
an error, then return an error; otherwise, return the number of milliseconds elapsed from midnight
UTC on the morning of 1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0Z") to midnight UTC on the morning of the Monday of the
parsed week, ignoring leap seconds.
The algorithm to convert a number to a
string, given a number input, is as follows: Return a
valid week string that represents the week that, in
UTC, is current input milliseconds after midnight UTC on the morning of
1970-01-01 (the time represented by the value "1970-01-01T00:00:00.0Z").
The algorithm to convert a string to a
Date object, given a string input, is as follows: If parsing a week from input results in an error, then
return an error; otherwise, return a new Date
object representing midnight UTC on the morning of the Monday of the parsed week.
The algorithm to convert a
Date object to a string, given a Date object input, is
as follows: Return a valid week string that represents the week current at the time represented by input in the UTC
time zone.
type=time)Support in all current engines.
When an input element's type attribute is in
the Time state, the rules in this section apply.
The input element represents a control for setting the element's
value to a string representing a specific time.
If the element is mutable, the user agent should allow the user to change the time represented by its value, as obtained by parsing a time from it. User agents must not allow the user to set the value to a non-empty string that is not a valid time string. If the user agent provides a user interface for selecting a time, then the value must be set to a valid time string representing the user's selection. User agents should allow the user to set the value to the empty string.
Constraint validation: While the user interface describes input that the user agent cannot convert to a valid time string, the control is suffering from bad input.
The value attribute, if specified and not empty, must
have a value that is a valid time string.
The value sanitization algorithm is as follows: If the value of the element is not a valid time string, then set it to the empty string instead.
The form control has a periodic domain.
The min attribute, if specified, must have a value that is
a valid time string. The max attribute, if
specified, must have a value that is a valid time string.
The step attribute is expressed in seconds. The step scale factor is 1000 (which
converts the seconds to milliseconds, as used in the other algorithms). The default step is 60 seconds.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest time for which the element would not suffer from a step mismatch.
The algorithm to convert a string to a number, given a string input, is as follows: If parsing a time from input results in an error, then return an error; otherwise, return the number of milliseconds elapsed from midnight to the parsed time on a day with no time changes.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid time string that represents the time that is input milliseconds after midnight on a day with no time changes.
The algorithm to convert a string to a
Date object, given a string input, is as
follows: If parsing a time from
input results
in an error, then return an error; otherwise, return a new
Date object representing the parsed time in
UTC on 1970-01-01.
The algorithm to convert a
Date object to a string, given a Date object input, is
as follows: Return a valid time string that represents the UTC time component that is represented by input.
type=datetime-local)Support in all current engines.
When an input element's type attribute is in
the Local Date and Time state, the rules in
this section apply.
The input element represents a control for setting the element's
value to a string representing a local date and time, with no time-zone offset
information.
If the element is mutable, the user agent should allow the user to change the date and time represented by its value, as obtained by parsing a date and time from it. User agents must not allow the user to set the value to a non-empty string that is not a valid normalized local date and time string. If the user agent provides a user interface for selecting a local date and time, then the value must be set to a valid normalized local date and time string representing the user's selection. User agents should allow the user to set the value to the empty string.
Constraint validation: While the user interface describes input that the user agent cannot convert to a valid normalized local date and time string, the control is suffering from bad input.
The value attribute, if specified and not empty, must
have a value that is a valid local date and time string.
The value sanitization algorithm is as follows: If the value of the element is a valid local date and time string, then set it to a valid normalized local date and time string representing the same date and time; otherwise, set it to the empty string instead.
The min attribute, if specified, must have a value that is
a valid local date and time string. The max
attribute, if specified, must have a value that is a valid local date and time
string.
The step attribute is expressed in seconds. The step scale factor is 1000 (which
converts the seconds to milliseconds, as used in the other algorithms). The default step is 60 seconds.
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest local date and time for which the element would not suffer from a step mismatch.
The algorithm to convert a string to a
number, given a string input, is as follows: If parsing a date and time from input results in an error, then return an error; otherwise, return the number of
milliseconds elapsed from midnight on the morning of 1970-01-01 (the time represented by the value
"1970-01-01T00:00:00.0") to the parsed local date and time, ignoring leap seconds.
The algorithm to convert a number to a
string, given a number input, is as follows: Return a
valid normalized local date and time string that represents the date and time that is
input milliseconds after midnight on the morning of 1970-01-01 (the time
represented by the value "1970-01-01T00:00:00.0").
type=number)Support in all current engines.
When an input element's type attribute is in
the Number state, the rules in this section apply.
The input element represents a control for setting the element's
value to a string representing a number.
If the element is mutable, the user agent should allow the user to change the number represented by its value, as obtained from applying the rules for parsing floating-point number values to it. User agents must not allow the user to set the value to a non-empty string that is not a valid floating-point number. If the user agent provides a user interface for selecting a number, then the value must be set to the best representation of the number representing the user's selection as a floating-point number. User agents should allow the user to set the value to the empty string.
Constraint validation: While the user interface describes input that the user agent cannot convert to a valid floating-point number, the control is suffering from bad input.
The value attribute, if specified and not empty, must
have a value that is a valid floating-point number.
The value sanitization algorithm is as follows: If the value of the element is not a valid floating-point number, then set it to the empty string instead.
The min attribute, if specified, must have a value that is
a valid floating-point number. The max attribute,
if specified, must have a value that is a valid floating-point number.
The step scale factor is 1. The default step is 1 (allowing only integers to be selected by the user, unless the step base has a non-integer value).
When the element is suffering from a step mismatch, the user agent may round the element's value to the nearest number for which the element would not suffer from a step mismatch. If there are two such numbers, user agents are encouraged to pick the one nearest positive infinity.
The algorithm to convert a string to a number, given a string input, is as follows: If applying the rules for parsing floating-point number values to input results in an error, then return an error; otherwise, return the resulting number.
The algorithm to convert a number to a string, given a number input, is as follows: Return a valid floating-point number that represents input.
type=range)Support in all current engines.
When an input element's type attribute is in
the Range state, the rules in this section apply.
The input element represents a control for setting the element's
value to a string representing a number, but with the
caveat that the exact value is not important, letting UAs provide a simpler interface than they
do for the Number state.
If the element is mutable, the user agent should allow the user to change the number represented by its value, as obtained from applying the rules for parsing floating-point number values to it. User agents must not allow the user to set the value to a string that is not a valid floating-point number. If the user agent provides a user interface for selecting a number, then the value must be set to a best representation of the number representing the user's selection as a floating-point number. User agents must not allow the user to set the value to the empty string.
Constraint validation: While the user interface describes input that the user agent cannot convert to a valid floating-point number, the control is suffering from bad input.
The value attribute, if specified, must have a value
that is a valid floating-point number.
The value sanitization algorithm is as follows: If the value of the element is not a valid floating-point number, then set it to the best representation, as a floating-point number, of the default value.
When the element is suffering from an underflow, the user agent must set the element's value to the best representation, as a floating-point number, of the minimum.
When the element is suffering from an overflow, if the maximum is not less than the minimum, the user agent must set the element's value to a valid floating-point number that represents the maximum.
When the element is suffering from a step mismatch, the user agent must round the element's value to the nearest number for which the element would not suffer from a step mismatch, and which is greater than or equal to the minimum, and, if the maximum is not less than the minimum, which is less than or equal to the maximum, if there is a number that matches these constraints. If two numbers match these constraints, then user agents must use the one nearest to positive infinity.
The min attribute, if specified, must have a value that is
a valid floating-point number. The default
minimum is 0. The max attribute, if specified, must
have a value that is a valid floating-point number. The default maximum is 100.
The step scale factor is
1. The default step is 1 (allowing only
integers, unless the min attribute has a non-integer
value).
The algorithm to convert a string to a number, given a string input, is as follows: If applying the rules for parsing floating-point number values to input results in an error, then return an error; otherwise, return the resulting number.
The algorithm to convert a number to a string, given a number input, is as follows: Return the best representation, as a floating-point number, of input.
type=color)Support in all current engines.
When an input element's type attribute is in
the Color state, the rules in this section apply.
The input element represents a color well control, for setting the
element's value to a string representing the serialization
of a CSS color.
The colorspace
attribute indicates the color space of the serialized CSS color. It also hints at the desired user
interface for selecting a CSS color. It is an enumerated attribute with the following
keywords and states:
| Keyword | State | Brief description |
|---|---|---|
limited-srgb
| Limited sRGB | The CSS color is converted to the 'srgb' color space and limited to 8-bits per
component, e.g., "#123456" or "color(srgb 0 1 0 / 0.5)".
|
display-p3
| Display P3 | The CSS color is converted to the 'display-p3' color space, e.g., "color(display-p3 1.84 -0.19 0.72 / 0.6)".
|
The attribute's missing value default and invalid value default are both the Limited sRGB state.
Whenever the element's alpha or colorspace attributes are changed, the user agent must run
update a color well control color given the element.
If the element is mutable, the user agent should allow the user to change the color represented by its value, as obtained from parsing it. User agents must not allow the user to set the value to a string that running update a color well control color for the element would not set it to. If the user agent provides a user interface for selecting a CSS color, then the value must be set to the result of serializing a color well control color given the element and the end user's selection.
The input activation behavior for such an element element is to show the picker, if applicable, for element.
Constraint validation: While the element's value is not the empty string and parsing it returns failure, the control is suffering from bad input.
The value attribute, if specified and not the empty
string, must have a value that is a CSS color.
The value sanitization algorithm is as follows: Run update a color well control color for the element.
type=checkbox)Support in all current engines.
When an input element's type attribute is in
the Checkbox state, the rules in this section
apply.
The input element represents a two-state control that represents the
element's checkedness state. If the element's checkedness state is true, the control represents a positive
selection, and if it is false, a negative selection. If the element's indeterminate IDL attribute is set to true, then the
control's selection should be obscured as if the control was in a third, indeterminate, state.
The input activation behavior is to run the following steps:
If the element is not connected, then return.
Fire an event named input at the element with the bubbles and composed
attributes initialized to true.
Fire an event named change at the element with the bubbles attribute initialized to true.
Constraint validation: If the element is required and its checkedness is false, then the element is suffering from being missing.
type=radio)Support in all current engines.
When an input element's type attribute is in
the Radio Button state, the rules in this section
apply.
The input element represents a control that, when used in conjunction
with other input elements, forms a radio button group in which only one
control can have its checkedness state set to true. If
the element's checkedness state is true, the control
represents the selected control in the group, and if it is false, it indicates a control in the
group that is not selected.
A tree must not contain an input element whose radio button group contains only that element.
When any of the following phenomena occur, if the element's checkedness state is true after the occurrence, the checkedness state of all the other elements in the same radio button group must be set to false:
name attribute is set, changed, or
removed.The input activation behavior is to run the following steps:
If the element is not connected, then return.
Fire an event named input at the element with the bubbles and composed
attributes initialized to true.
Fire an event named change at the element with the bubbles attribute initialized to true.
Constraint validation: If an element in the radio button group is required, and all of the
input elements in the radio button group have a
checkedness that is false, then the element is
suffering from being missing.
type=file)Support in all current engines.
When an input element's type attribute is in
the File Upload state, the rules in this section
apply.
Unless the multiple attribute is set, there must be
no more than one file in the list of selected
files.
The input activation behavior for such an element element is to show the picker, if applicable, for element.
If the element is mutable, the user agent should allow the user to change the files on the list in other ways also, e.g., adding or removing files by drag-and-drop. When the user does so, the user agent must update the file selection for the element.
If the element is not mutable, the user agent must not allow the user to change the element's selection.
Constraint validation: If the element is required and the list of selected files is empty, then the element is suffering from being missing.
Support in all current engines.
Support in all current engines.
If specified, the attribute must consist of a set of comma-separated tokens, each of which must be an ASCII case-insensitive match for one of the following:
audio/*"video/*"image/*"The tokens must not be ASCII case-insensitive matches for any of the other tokens (i.e. duplicates are not allowed). To obtain the list of tokens from the attribute, the user agent must split the attribute value on commas.
User agents may use the value of this attribute to display a more appropriate user interface
than a generic file picker. For instance, given the value image/*, a user
agent could offer the user the option of using a local camera or selecting a photograph from their
photo collection; given the value audio/*, a user agent could offer the user
the option of recording a clip using a headset microphone.
User agents should prevent the user from selecting files that are not accepted by one (or more) of these tokens.
type=submit)Support in all current engines.
When an input element's type attribute is in
the Submit Button state, the rules in this section
apply.
The
input element represents a button that, when activated, submits the
form. If the element has a value attribute,
the button's label must be the value of that attribute; otherwise, it must be an
implementation-defined string that means "Submit" or some such. The element is
a button, specifically a submit button.
The element's input activation behavior given event is as follows:
If the element does not have a form owner, then return.
If the element's node document is not fully active, then return.
Submit the element's form owner from the element with userInvolvement set to event's user navigation involvement.
The formaction, formenctype, formmethod, formnovalidate, and formtarget attributes are attributes for form
submission.
type=image)Support in all current engines.
When an input element's type attribute is in
the Image Button state, the rules in this section
apply.
The input element represents either an image from which a user can
select a coordinate and submit the form, or alternatively a button from which the user can submit
the form. The element is a button, specifically a submit button.
Support in all current engines.
When any of the these events occur
input element's type attribute is
first set to the Image Button state (possibly when
the element is first created), and the src attribute is
presentinput element's type attribute is
changed back to the Image Button state, and the src attribute is present, and its value has changed since the last
time the type attribute was in the Image Button stateinput element's type attribute is in
the Image Button state, and the src attribute is set or changedthen unless the user agent cannot support images, or its support for images has been disabled,
or the user agent only fetches images on demand, or the src
attribute's value is the empty string, run these steps:
Let url be the result of encoding-parsing a URL given the src attribute's value, relative to the element's node
document.
If url is failure, then return.
Let request be a new request whose URL is url, client is the element's node document's
relevant settings object, destination is "image", initiator type is "input",
credentials mode is "include", and whose use-URL-credentials flag is set.
Fetch request, with processResponseEndOfBody set to the following step given response response:
If the download was successful and the image is available, queue an element task on the
user interaction task source given the input element to fire an event named load
at the input element.
Otherwise, if the fetching process fails without a response from the remote server, or
completes but the image is not a valid or supported image, then queue an element
task on the user interaction task source given the input
element to fire an event named error on the input element.
Fetching the image must delay the load event of the element's node document until the task that is queued by the networking task source once the resource has been fetched (defined below) has been run.
The user agent should apply the image sniffing rules to determine the type of the image, with the image's associated Content-Type headers giving the official type. If these rules are not applied, then the type of the image must be the type given by the image's associated Content-Type headers.
User agents must not support non-image resources with the input element. User
agents must not run executable code embedded in the image resource. User agents must only display
the first page of a multipage resource. User agents must not allow the resource to act in an
interactive fashion, but should honor any animation in the resource.
Support in all current engines.
The input element supports dimension attributes.
If the src attribute is set, and the image is available and the user agent is configured to display that image,
then the element represents a control for selecting a coordinate from the image specified by the
src attribute. In that case, if the element is mutable, the user agent should allow the user to select this coordinate.
Otherwise, the element represents a submit button whose label is given by the
value of the alt attribute.
The element's input activation behavior given event is as follows:
If the element does not have a form owner, then return.
If the element's node document is not fully active, then return.
If the user activated the control while explicitly selecting a coordinate, then set the element's selected coordinate to that coordinate.
Submit the element's form owner from the element with userInvolvement set to event's user navigation involvement.
The x-component must be a valid integer representing a number x in the range −(borderleft+paddingleft) ≤ x ≤ width+borderright+paddingright, where width is the rendered width of the image, borderleft is the width of the border on the left of the image, paddingleft is the width of the padding on the left of the image, borderright is the width of the border on the right of the image, and paddingright is the width of the padding on the right of the image, with all dimensions given in CSS pixels.
The y-component must be a valid integer representing a number y in the range −(bordertop+paddingtop) ≤ y ≤ height+borderbottom+paddingbottom, where height is the rendered height of the image, bordertop is the width of the border above the image, paddingtop is the width of the padding above the image, borderbottom is the width of the border below the image, and paddingbottom is the width of the padding below the image, with all dimensions given in CSS pixels.
Where a border or padding is missing, its width is zero CSS pixels.
The formaction, formenctype, formmethod, formnovalidate, and formtarget attributes are attributes for form
submission.
type=reset)Support in all current engines.
When an input element's type attribute is in
the Reset Button state, the rules in this section
apply.
The
input element represents a button that, when activated, resets the
form. If the element has a value attribute,
the button's label must be the value of that attribute; otherwise, it must be an
implementation-defined string that means "Reset" or some such. The element is
a button.
The element's input activation behavior is as follows:
If the element does not have a form owner, then return.
If the element's node document is not fully active, then return.
Reset the form owner from the element.
Constraint validation: The element is barred from constraint validation.
type=button)Support in all current engines.
When an input element's type attribute is in
the Button state, the rules in this section apply.
The input element represents a button with no default behavior. A
label for the button must be provided in the value
attribute, though it may be the empty string. If the element has a value attribute, the button's label must be the value of that
attribute; otherwise, it must be the empty string. The element is a button.
The element has no input activation behavior.
Constraint validation: The element is barred from constraint validation.
This section is non-normative.
The formats shown to the user in date, time, and number controls is independent of the format used for form submission.
Browsers are encouraged to use user interfaces that present dates, times, and numbers according
to the conventions of either the locale implied by the input element's
language or the user's preferred locale. Using the page's locale will ensure
consistency with page-provided data.
input element attributesThese attributes only apply to an input
element if its type attribute is in a state whose definition
declares that the attribute applies. When an attribute
doesn't apply to an input element, user agents must
ignore the attribute, regardless of the requirements and definitions below.
maxlength and minlength attributesSupport in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
The maxlength
attribute, when it applies, is a
form control maxlength
attribute.
Support in all current engines.
If the input element has a maximum allowed value length, then the
length of the value of the element's value
attribute must be less than or equal to the element's maximum allowed value
length.
size attributeThe size attribute, if specified, must have a value that
is a valid non-negative integer greater than zero.
If the attribute is present, then its value must be parsed using the rules for parsing non-negative integers, and if the result is a number greater than zero, then the user agent should ensure that at least that many characters are visible.
The size IDL attribute is limited to only positive
numbers and has a default value of 20.
readonly attributeSupport in all current engines.
Support in all current engines.
Support in all current engines.
Constraint validation: If the readonly attribute is specified on an input
element, the element is barred from constraint validation.
required attributeConstraint validation: If the element is required, and its value
IDL attribute applies and is in the mode value, and the element is mutable, and the element's value is the empty string, then the element is suffering
from being missing.
multiple attributeSupport in all current engines.
Support in all current engines.
The multiple
attribute is a boolean attribute that indicates whether the user is to be allowed to
specify more than one value.
pattern attributeSupport in all current engines.
Support in all current engines.
If specified, the attribute's value must match the JavaScript Pattern[+UnicodeSetsMode, +N] production.
Constraint validation: If the element's value is not the empty string, and either the element's multiple attribute is not specified or it does not apply to the input element given its type attribute's current state, and the element has a
compiled pattern regular expression but that regular expression does not match the element's value, then the element is suffering from a pattern
mismatch.
Constraint validation: If the element's value is not the empty string, and the element's multiple attribute is specified and applies to the input element, and the element has
a compiled pattern regular expression but that regular expression does not match each of the element's values, then the element is suffering from a pattern
mismatch.
When a control has a pattern attribute, the title attribute, if used, must describe the pattern. Additional
information could also be included, so long as it assists the user in filling in the control.
Otherwise, assistive technology would be impaired.
UAs may still show the title in non-error situations (for
example, as a tooltip when hovering over the control), so authors should be careful not to word
titles as if an error has necessarily occurred.
min and max attributesSupport in all current engines.
Support in all current engines.
Their syntax is defined by the section that defines the type attribute's current state.
The min attribute also defines the step base.
If the element does not have a periodic domain, the
max attribute's value (the maximum) must not be less than the min attribute's value (its minimum).
Constraint validation: When the element has a minimum and does not have a reversed range, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and the number obtained from that algorithm is less than the minimum, the element is suffering from an underflow.
Constraint validation: When the element has a maximum and does not have a reversed range, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and the number obtained from that algorithm is more than the maximum, the element is suffering from an overflow.
Constraint validation: When an element has a reversed range, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and the number obtained from that algorithm is more than the maximum and less than the minimum, the element is simultaneously suffering from an underflow and suffering from an overflow.
step attributeSupport in all current engines.
The step attribute, if specified, must either have a
value that is a valid floating-point number that parses to a number that is greater than zero, or must have a
value that is an ASCII case-insensitive match for the string "any".
Constraint validation: When the element has an allowed value step, and the result of applying the algorithm to convert a string to a number to the string given by the element's value is a number, and that number subtracted from the step base is not an integral multiple of the allowed value step, the element is suffering from a step mismatch.
list attributeSupport in all current engines.
If present, its value must be the ID of a datalist
element in the same tree.
If there is a suggestions source element, then, when
the user agent is allowing the user to edit the input element's value, the user agent should offer the suggestions represented by
the suggestions source element to the user in a manner
suitable for the type of control used. If appropriate, the user agent should use the suggestion's
label and value to identify the suggestion to the user.
User agents are encouraged to filter the suggestions represented by the suggestions source element when the number of suggestions is large, including only the most relevant ones (e.g. based on the user's input so far). No precise threshold is defined, but capping the list at four to seven values is reasonable. If filtering based on the user's input, user agents should search within both the label and value of the suggestions for matches. User agents should consider how input variations affect the matching process. Unicode normalization should be applied so that different underlying Unicode code point sequences, caused by different keyboard- or input-specific mechanisms, do not interfere with the matching process. Case variations should be ignored, which may require language-specific case mapping. For examples of these, see Character Model for the World Wide Web: String Matching. User agents may also provide other matching features: for illustration, a few examples include matching different forms of kana to each other (or to kanji), ignoring accents, or applying spelling correction. [CHARMODNORM]
How user selections of suggestions are handled depends on whether the element is a control accepting a single value only, or whether it accepts multiple values:
multiple attribute
specified or if the multiple attribute does not applyWhen the user selects a suggestion, the input element's value must be set to the selected suggestion's value, as if the user had written that value themself.
type attribute is in the Email state and the element has a multiple attribute specifiedWhen the user selects a suggestion, the user agent must either add a new entry to the
input element's values, whose value
is the selected suggestion's value, or change an
existing entry in the input element's values to have the value given by the selected
suggestion's value, as if the user had themself added
an entry with that value, or edited an existing entry to be that value. Which behavior is to be
applied depends on the user interface in an implementation-defined manner.
If the list attribute does not
apply, there is no suggestions source element.
placeholder attributeSupport in all current engines.
Element/input#attr-placeholder
Support in all current engines.
The placeholder attribute should not be used as an
alternative to a label. For a longer hint or other advisory text, the title attribute is more appropriate.
User agents should present this hint to the user, after having stripped newlines from it, when the element's value is the empty string, especially if the control is not focused.
If a user agent normally doesn't show this hint to the user when the control is
focused, then the user agent should nonetheless show the hint for the control if it
was focused as a result of the autofocus attribute, since
in that case the user will not have had an opportunity to examine the control before focusing
it.
input element APIsThe checked
IDL attribute allows scripts to manipulate the checkedness of an input element. On getting, it
must return the current checkedness of the element; and
on setting, it must set the element's checkedness to the
new value and set the element's dirty checkedness
flag to true.
On getting, if the IDL attribute applies, it must
return a FileList object that represents the current selected files. The same object must be returned
until the list of selected files changes.
If the IDL attribute does not apply, then it must instead
return null. [FILEAPI]
On setting, it must run these steps:
If the IDL attribute does not apply or the given value is null, then return.
Replace the element's selected files with the given value.
On getting, if the valueAsDate attribute does not apply, as defined for the input element's type attribute's current state, then return null. Otherwise, run
the algorithm to convert a string to a
Date object defined for that state to the element's value; if the algorithm returned a Date object, then
return it, otherwise, return null.
On setting, if the valueAsDate attribute does not apply, as defined for the input element's type attribute's current state, then throw an
"InvalidStateError" DOMException; otherwise, if the new
value is not null and not a Date object throw a TypeError exception;
otherwise, if the new value is null or a Date object representing the NaN time value,
then set the value of the element to the empty string;
otherwise, run the algorithm to convert a
Date object to a string, as defined for that state, on the new value, and set
the value of the element to the resulting string.
On getting, if the valueAsNumber attribute does not apply, as defined for the input element's type attribute's current state, then return a Not-a-Number (NaN)
value. Otherwise, run the algorithm to convert a
string to a number defined for that state to the element's value; if the algorithm returned a number, then return it,
otherwise, return a Not-a-Number (NaN) value.
On setting, if the new value is infinite, then throw a TypeError exception.
Otherwise, if the valueAsNumber attribute does not apply, as defined for the input element's type attribute's current state, then throw an
"InvalidStateError" DOMException. Otherwise, if the new
value is a Not-a-Number (NaN) value, then set the value of
the element to the empty string. Otherwise, run the algorithm to convert a number to a string, as
defined for that state, on the new value, and set the value
of the element to the resulting string.
The list IDL
attribute must return the current suggestions source
element, if any, or null otherwise.
Support in all current engines.
The HTMLInputElement showPicker() and HTMLSelectElement showPicker()
method steps are:
If this is not mutable, then throw
an "InvalidStateError" DOMException.
If this's relevant settings object's origin is not same origin with
this's relevant settings object's top-level origin, and
this is a select element, or
this's type attribute is not in the File Upload state or Color state, then throw a
"SecurityError" DOMException.
If this's relevant global object does not have transient
activation, then throw a "NotAllowedError"
DOMException.
If this is a select element, and this is not
being rendered, then throw a "NotSupportedError"
DOMException.
When the input and change events apply
(which is the case for all input controls other than buttons and those with the type attribute in the state), the events are fired to indicate that the
user has interacted with the control. The input event fires
whenever the user has modified the data of the control. The change event fires when the value is committed, if that makes sense
for the control, or else when the control loses focus.
In all cases, the input event comes before the corresponding
change event (if any).
When an input element has a defined input activation behavior, the
rules for dispatching these events, if they apply, are
given in the section above that defines the type attribute's
state. (This is the case for all input controls with the type attribute in the Checkbox state, the Radio Button state, or the File Upload state.)
For input elements without a defined input activation behavior, but
to which these events apply, and for which the user
interface involves both interactive manipulation and an explicit commit action, then when the
user changes the element's value, the user agent must
queue an element task on the user interaction task source given the
input element to fire an event named input at the input element, with the bubbles and composed
attributes initialized to true, and any time the user commits the change, the user agent must
queue an element task on the user interaction task source given the
input element to set its user validity to true and fire an event named change
at the input element, with the bubbles
attribute initialized to true.
For input elements without a defined input activation behavior, but
to which these events apply, and for which the user
interface involves an explicit commit action but no intermediate manipulation, then any time the
user commits a change to the element's value, the user
agent must queue an element task on the user interaction task source
given the input element to first fire an
event named input at the input element, with
the bubbles and composed attributes initialized to true, and then fire an event named change
at the input element, with the bubbles
attribute initialized to true.
For input elements without a defined input activation behavior, but
to which these events apply, any time the user causes
the element's value to change without an explicit commit
action, the user agent must queue an element task on the user interaction task
source given the input element to fire an
event named input at the input element, with
the bubbles and composed attributes initialized to true. The corresponding
change event, if any, will be fired when the control loses focus.
In the case of tasks that just fire an input event, user agents may wait for a suitable break in the user's
interaction before queuing the tasks; for example, a
user agent could wait for the user to have not hit a key for 100ms, so as to only fire the event
when the user pauses, instead of continuously for each keystroke.
When the user agent is to change an input element's value on behalf of the user (e.g. as part of a form prefilling
feature), the user agent must queue an element task on the user interaction
task source given the input element to first update the value accordingly, then fire an
event named input at the input element, with
the bubbles and composed attributes initialized to true, then fire an event named change
at the input element, with the bubbles
attribute initialized to true.
button elementSupport in all current engines.
Support in all current engines.
tabindex attribute
specified.disabled — Whether the form control is disabled
form — Associates the element with a form element
formaction — URL to use for form submission
formenctype — Entry list encoding type to use for form submission
formmethod — Variant to use for form submission
formnovalidate — Bypass form control validation for form submission
formtarget — Navigable for form submission
name — Name of the element to use for form submission and in the form.elements API
popovertarget — Targets a popover element to toggle, show, or hide
popovertargetaction — Indicates whether a targeted popover element is to be toggled, shown, or hidden
type — Type of button
value — Value to be used for form submission
The button element represents a button labeled by its contents.
The element is a button.
The type attribute
controls the behavior of the button when it is activated. It is an enumerated
attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
submit
| Submit Button | Submits the form. |
reset
| Reset Button | Resets the form. |
button
| Button | Does nothing. |
The attribute's missing value default and invalid value default are both the Submit Button state.
If the type attribute is in the Submit Button state, the element is specifically a
submit button.
Constraint validation: If the type
attribute is in the Reset Button state or the
Button state, the element is barred from
constraint validation.
A button element element's activation behavior given
event is:
If element is disabled, then return.
If element's node document is not fully active, then return.
If element has a form owner then switch on element's type attribute's state, then:
Submit element's form owner from element with userInvolvement set to event's user navigation involvement.
Reset element's form owner.
Do nothing.
Run the popover target attribute activation behavior given element and event's target.
The form attribute is used to explicitly associate the
button element with its form owner. The name attribute represents the element's name. The disabled attribute is used to make the control non-interactive and
to prevent its value from being submitted. The formaction,
formenctype, formmethod, formnovalidate, and formtarget attributes are attributes for form
submission.
The formaction, formenctype, formmethod, formnovalidate, and formtarget must not be specified if the element's type attribute is not in the Submit Button state.
The value
attribute gives the element's value for the purposes of form submission. The element's value is the value of the element's value attribute, if there is one, or the empty string
otherwise.
The willValidate, validity, and validationMessage IDL attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the
constraint validation API. The labels IDL
attribute provides a list of the element's labels. The disabled, form, and
name IDL attributes are part of the element's forms API.
select elementSupport in all current engines.
Support in all current engines.
option, optgroup, hr, and script-supporting elements.autocomplete — Hint for form autofill feature
disabled — Whether the form control is disabled
form — Associates the element with a form element
multiple — Whether to allow multiple values
name — Name of the element to use for form submission and in the form.elements API
required — Whether the control is required for form submission
size — Size of the control
multiple attribute or a size attribute with a value > 1: for authors; for implementers.The select element represents a control for selecting amongst a set of
options.
Support in all current engines.
The multiple
attribute is a boolean attribute. If the attribute is present, then the
select element represents a control for selecting zero or more options
from the list of options. If the attribute is
absent, then the select element represents a control for selecting a
single option from the list of options.
Support in all current engines.
The list of options for a select
element consists of all the option element children of the select
element, and all the option element children of all the optgroup element
children of the select element, in tree order.
Support in all current engines.
If a select element has a required
attribute specified, does not have a multiple attribute
specified, and has a display size of 1, then the
select element must have a placeholder label option.
Constraint validation: If the element has its required attribute specified, and either none of the
option elements in the select element's list of options have their selectedness set to true, or the only
option element in the select element's list of options with its selectedness set to true is the placeholder label
option, then the element is suffering from being missing.
If the multiple attribute is absent, whenever an
option element in the select element's list of options has its selectedness set to true, and whenever an
option element with its selectedness set to true is added to the
select element's list of options,
the user agent must set the selectedness of all
the other option elements in its list of
options to false.
If the multiple attribute is absent and the
element's display size is greater than 1, then the user
agent should also allow the user to request that the option whose selectedness is true, if any, be unselected. Upon this
request being conveyed to the user agent, and before the relevant user interaction event is queued (e.g. before the click event), the user agent must set the selectedness of that option element to
false, set its dirtiness to true, and then
send select update notifications.
The option HTML element insertion
steps, given insertedNode, are:
If insertedNode's parent is a select element, or
insertedNode's parent is an optgroup element whose parent is a
select element, then run that select element's selectedness
setting algorithm.
The option HTML element removing
steps, given removedNode and oldParent, are:
If oldParent is a select element, or oldParent is an
optgroup element whose parent is a select element, then run that
select element's selectedness setting algorithm.
The optgroup HTML element removing
steps, given removedNode and oldParent, are:
If oldParent is a select element and removedNode has an
option child, then run oldParent's selectedness setting
algorithm.
The reset algorithm for a select
element selectElement is:
Set selectElement's user validity to false.
For each optionElement of selectElement's list of options:
If optionElement has a selected
attribute, then set optionElement's selectedness to true; otherwise set it to
false.
Set optionElement's dirtiness to false.
Run the selectedness setting algorithm given selectElement.
The form attribute is used to explicitly associate the select element with its form owner.
The name attribute represents the element's name.
The disabled attribute is used to make the control non-interactive and to prevent its value from being submitted.
The autocomplete attribute controls how the user agent provides autofill behavior.
A select element that is not disabled is
mutable.
The options collection is also mirrored on the
HTMLSelectElement object. The supported property indices at any instant
are the indices supported by the object returned by the options attribute at that instant.
When the user agent is to set the value of a new indexed
property or set the value of an existing indexed property for a
select element, it must instead run the
corresponding algorithm on the select element's options collection.
Similarly, the add(element, before) method must act
like its namesake method on that same options
collection.
Support in all current engines.
On setting, the selectedIndex attribute must set
the selectedness of all the option
elements in the list of options to false, and
then the option element in the list of
options whose index is the given new value, if
any, must have its selectedness set to true and
its dirtiness set to true.
On setting, the value attribute must set the selectedness of all the option elements
in the list of options to false, and then the
first option element in the list of
options, in tree order, whose value
is equal to the given new value, if any, must have its selectedness set to true and its dirtiness set to true.
The willValidate, validity, and validationMessage IDL attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the
constraint validation API. The labels IDL
attribute provides a list of the element's labels. The disabled, form, and
name IDL attributes are part of the element's forms API.
datalist elementSupport in all current engines.
option and script-supporting elements.The datalist element represents a set of option elements that
represent predefined options for other controls. In the rendering, the datalist
element represents nothing and it, along with its children, should
be hidden.
The datalist element can be used in two ways. In the simplest case, the
datalist element has just option element children.
In the more elaborate case, the datalist element can be given contents that are to
be displayed for down-level clients that don't support datalist. In this case, the
option elements are provided inside a select element inside the
datalist element.
The datalist element is hooked up to an input element using the list attribute on the input element.
Each option element that is a descendant of the datalist element,
that is not disabled, and whose value is a string that isn't the empty string, represents a
suggestion. Each suggestion has a value and a label.
Constraint validation: If an element has a datalist element
ancestor, it is barred from constraint validation.
optgroup elementSupport in all current engines.
Support in all current engines.
select element.option and script-supporting elements.optgroup element's end tag can be omitted
if the optgroup element is
immediately followed by another optgroup element, if it is immediately followed by an
hr element, or if there is no more content in the parent
element.disabled — Whether the form control is disabled
label — User-visible label
The optgroup element represents a group of option
elements with a common label.
The element's group of option elements consists of the option
elements that are children of the optgroup element.
When showing option elements in select elements, user agents should
show the option elements of such groups as being related to each other and separate
from other option elements.
Support in all current engines.
The disabled and label attributes must
reflect the respective content attributes of the same name.
option elementSupport in all current engines.
Support in all current engines.
select element.datalist element.optgroup element.label attribute and a value attribute: Nothing.label attribute but no value attribute: Text.label attribute and is not a
child of a datalist element: Text that is not
inter-element whitespace.label attribute and is a child
of a datalist element: Text.option element's end tag can be omitted if
the option element is immediately followed by another option element, if
it is immediately followed by an optgroup element, if it is immediately followed by
an hr element, or if there is no more content in the parent element.disabled — Whether the form control is disabled
label — User-visible label
selected — Whether the option is selected by default
value — Value to be used for form submission
The option element represents an option in a select
element or as part of a list of suggestions in a datalist element.
In certain circumstances described in the definition of the select element, an
option element can be a select element's placeholder label
option. A placeholder label option does not represent an actual option, but
instead represents a label for the select control.
Support in all current engines.
An option element that is disabled must
prevent any click events that are queued on the user interaction task source from being dispatched on the
element.
The label content attribute, if specified, must not be
empty.
A select element whose multiple
attribute is not specified must not have more than one descendant option element with
its selected attribute set.
The disabled IDL attribute must reflect the
content attribute of the same name. The defaultSelected IDL attribute must
reflect the selected content
attribute.
The text attribute's setter must string replace
all with the given value within this element.
textarea elementSupport in all current engines.
Support in all current engines.
autocomplete — Hint for form autofill feature
cols — Maximum number of characters per line
dirname — Name of form control to use for sending the element's directionality in form submission
disabled — Whether the form control is disabled
form — Associates the element with a form element
maxlength — Maximum length of value
minlength — Minimum length of value
name — Name of the element to use for form submission and in the form.elements API
placeholder — User-visible label to be placed within the form control
readonly — Whether to allow the value to be edited by the user
required — Whether the control is required for form submission
rows — Number of lines to show
wrap — How the value of the form control is to be wrapped for form submission
The raw value of a textarea
control must be initially the empty string.
Constraint validation: If the readonly attribute is specified on a textarea
element, the element is barred from constraint validation.
A textarea element is mutable if it is
neither disabled nor has a readonly attribute specified.
When a textarea is mutable, its raw value should be editable by the user: the user
agent should allow the user to edit, insert, and remove text, and to insert and remove line breaks
in the form of U+000A LINE FEED (LF) characters. Any time the user causes the element's raw value to change, the user agent must queue an
element task on the user interaction task source given the
textarea element to fire an event named
input at the textarea element, with the bubbles and composed
attributes initialized to true. User agents may wait for a suitable break in the user's
interaction before queuing the task; for example, a user agent could wait for the user to have not
hit a key for 100ms, so as to only fire the event when the user pauses, instead of continuously
for each keystroke.
A textarea element's dirty value flag must
be set to true whenever the user interacts with the control in a way that changes the raw value.
The cloning steps for textarea
elements given node, copy, and subtree are to propagate the raw value and dirty
value flag from node to copy.
The children changed steps for textarea elements must, if the
element's dirty value flag is false, set the element's
raw value to its child text
content.
The reset algorithm for textarea
elements is to set the user validity to false, dirty value flag back to false, and set the raw value of element to its child text
content.
When a textarea element is popped off the stack of open elements of
an HTML parser or XML parser, then the user agent must invoke the
element's reset algorithm.
If the element is mutable, the user agent should allow the user to change the writing direction of the element, setting it either to a left-to-right writing direction or a right-to-left writing direction. If the user does so, the user agent must then run the following steps:
Set the element's dir attribute to "ltr" if the user selected a left-to-right writing direction, and
"rtl" if the user selected a right-to-left writing
direction.
Queue an element task on the user interaction task source given
the textarea element to fire an event named
input at the textarea element, with the bubbles and composed
attributes initialized to true.
The cols
attribute specifies the expected maximum number of characters per line. If the cols attribute is specified, its value must be a valid
non-negative integer greater than zero. If applying the rules for
parsing non-negative integers to the attribute's value results in a number greater than
zero, then the element's character width is that
value; otherwise, it is 20.
The user agent may use the textarea element's character width as a hint to the user as to how many
characters the server prefers per line (e.g. for visual user agents by making the width of the
control be that many characters). In visual renderings, the user agent should wrap the user's
input in the rendering so that each line is no wider than this number of characters.
The rows
attribute specifies the number of lines to show. If the rows attribute is specified, its value must be a valid
non-negative integer greater than zero. If applying the rules for
parsing non-negative integers to the attribute's value results in a number greater than
zero, then the element's character height is that
value; otherwise, it is 2.
Visual user agents should set the height of the control to the number of lines given by character height.
The wrap
attribute is an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
soft
| Soft | Text is not to be wrapped when submitted (though can still be wrapped in the rendering). |
hard
| Hard | Text is to have newlines added by the user agent so that the text is wrapped when it is submitted. |
The attribute's missing value default and invalid value default are both the Soft state.
If the element's wrap attribute is in the Hard state, the cols attribute must be specified.
For historical reasons, the element's value is normalized in three different ways for three
different purposes. The raw value is the value as
it was originally set. It is not normalized. The API
value is the value used in the value IDL
attribute, textLength IDL attribute, and by the
maxlength and minlength content attributes. It is normalized so that line
breaks use U+000A LINE FEED (LF) characters. Finally, there is the value, as used in form submission and other processing models in
this specification. It is normalized as for the API
value, and in addition, if necessary given the element's wrap attribute, additional line breaks are inserted to wrap the
text at the given width.
The algorithm for obtaining the element's API value is to return the element's raw value, with newlines normalized.
If the textarea element has a maximum allowed value length, then the
element's children must be such that the length of the value of the element's
descendant text content with newlines
normalized is less than or equal to the element's maximum allowed value
length.
Constraint validation: If the element has its required attribute specified, and the element is mutable, and the element's value is the empty string, then the element is suffering
from being missing.
The placeholder attribute should not be used as
an alternative to a label. For a longer hint or other advisory text, the title attribute is more appropriate.
User agents should present this hint to the user when the element's value is the empty string and the control is not focused (e.g. by displaying it inside a blank unfocused control). All U+000D CARRIAGE RETURN U+000A LINE FEED character pairs (CRLF) in the hint, as well as all other U+000D CARRIAGE RETURN (CR) and U+000A LINE FEED (LF) characters in the hint, must be treated as line breaks when rendering the hint.
If a user agent normally doesn't show this hint to the user when the control is
focused, then the user agent should nonetheless show the hint for the control if it
was focused as a result of the autofocus attribute, since
in that case the user will not have had an opportunity to examine the control before focusing
it.
The name attribute represents the element's name.
The dirname attribute controls how the element's directionality is submitted.
The disabled attribute is used to make the control
non-interactive and to prevent its value from being submitted.
The form attribute is used to explicitly associate the
textarea element with its form owner.
The autocomplete attribute controls how the user agent
provides autofill behavior.
The cols, placeholder, required, rows, and wrap IDL
attributes must reflect the respective content attributes of the same name. The cols and rows attributes
are limited to only positive numbers with fallback. The cols IDL attribute's default value is 20. The rows IDL attribute's default value is 2. The dirName IDL
attribute must reflect the dirname content
attribute. The maxLength IDL attribute must reflect the
maxlength content attribute, limited to only
non-negative numbers. The minLength IDL attribute must reflect the
minlength content attribute, limited to only
non-negative numbers. The readOnly IDL attribute must reflect the
readonly content attribute.
The defaultValue attribute's setter must
string replace all with the given value within this element.
The willValidate, validity, and validationMessage IDL attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the
constraint validation API. The labels IDL
attribute provides a list of the element's labels. The select(), selectionStart, selectionEnd, selectionDirection, setRangeText(), and setSelectionRange() methods and IDL attributes
expose the element's text selection. The disabled,
form, and name IDL attributes
are part of the element's forms API.
output elementSupport in all current engines.
Support in all current engines.
for — Specifies controls from which the output was calculated
form — Associates the element with a form element
name — Name of the element to use in the form.elements API.The output element represents the result of a calculation performed
by the application, or the result of a user action.
Support in all current engines.
The form attribute is used to explicitly associate the
output element with its form owner. The name attribute represents the element's name. The output
element is associated with a form so that it can be easily referenced from the event
handlers of form controls; the element's value itself is not submitted when the form is
submitted.
The reset algorithm for output
elements is to run these steps:
String replace all with this element's default value within this element.
Set this element's default value override to null.
The value setter steps are:
Set this's default value override to its default value.
String replace all with the given value within this.
The defaultValue setter steps are:
If this's default value override is null, then string replace all with the given value within this and return.
Set this's default value override to the given value.
The willValidate, validity, and validationMessage IDL attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the
constraint validation API. The labels IDL
attribute provides a list of the element's labels. The form and name IDL attributes are
part of the element's forms API.
progress elementSupport in all current engines.
Support in all current engines.
progress element descendants.value — Current value of the element
max — Upper bound of range
The progress element represents the completion progress of a task.
The progress is either indeterminate, indicating that progress is being made but that it is not
clear how much more work remains to be done before the task is complete (e.g. because the task is
waiting for a remote host to respond), or the progress is a number in the range zero to a maximum,
giving the fraction of work that has so far been completed.
Support in all current engines.
There are two attributes that determine the current task completion represented by the element.
The value
attribute specifies how much of the task has been completed, and the max attribute specifies how much work
the task requires in total. The units are arbitrary and not specified.
Authors are encouraged to also include the current value and the maximum value inline as text inside the element, so that the progress is made available to users of legacy user agents.
The value and max attributes, when present, must have values that are valid floating-point numbers. The value attribute, if present, must have a value greater than or
equal to zero, and less than or equal to the value of the max attribute, if present, or 1.0, otherwise. The max attribute, if present, must have a value greater than
zero.
User agent requirements: If the value
attribute is omitted, then the progress bar is an indeterminate progress bar. Otherwise, it is a
determinate progress bar.
UA requirements for showing the progress bar: When representing a
progress element to the user, the UA should indicate whether it is a determinate or
indeterminate progress bar, and in the former case, should indicate the relative position of the
current value relative to the maximum value.
The labels IDL attribute provides a list of the element's
labels.
meter elementSupport in all current engines.
Support in all current engines.
meter element descendants.value — Current value of the element
min — Lower bound of range
max — Upper bound of range
low — High limit of low range
high — Low limit of high range
optimum — Optimum value in gauge
The meter element represents a scalar measurement within a known
range, or a fractional value; for example disk usage, the relevance of a query result, or the
fraction of a voting population to have selected a particular candidate.
This is also known as a gauge.
The meter element should not be used to indicate progress (as in a progress bar).
For that role, HTML provides a separate progress element.
There are six attributes that determine the semantics of the gauge represented by the element.
Support in all current engines.
Support in all current engines.
The min attribute
specifies the lower bound of the range, and the max attribute specifies the upper bound. The value attribute specifies
the value to have the gauge indicate as the "measured" value.
The other three attributes can be used to segment the gauge's range into "low", "medium", and
"high" parts, and to indicate which part of the gauge is the "optimum" part. The low attribute specifies the range that is
considered to be the "low" part, and the high attribute specifies the range that is considered to be
the "high" part. The optimum attribute gives the position that is "optimum";
if that is higher than the "high" value then this indicates that the higher the value, the better;
if it's lower than the "low" mark then it indicates that lower values are better, and naturally if
it is in between then it indicates that neither high nor low values are good.
Authoring requirements: The value attribute must be specified. The value, min, low, high, max, and optimum attributes,
when present, must have values that are valid
floating-point numbers.
In addition, the attributes' values are further constrained:
Let value be the value attribute's
number.
If the min attribute is specified, then let minimum be that attribute's value; otherwise, let it be zero.
If the max attribute is specified, then let maximum be that attribute's value; otherwise, let it be 1.0.
The following inequalities must hold, as applicable:
minimum ≤ value ≤ maximum
Authors are encouraged to include a textual representation of the gauge's state in the
element's contents, for users of user agents that do not support the meter
element.
When used with microdata, the meter element's value attribute provides the element's machine-readable value.
There is no explicit way to specify units in the meter element, but the units may
be specified in the title attribute in free-form text.
User agent requirements: User agents must parse the min, max, value, low, high, and optimum
attributes using the rules for parsing floating-point number values.
User agents must then use all these numbers to obtain values for six points on the gauge, as follows. (The order in which these are evaluated is important, as some of the values refer to earlier ones.)
If the min attribute is specified and a value could be
parsed out of it, then the minimum value is that value. Otherwise, the minimum value is
zero.
If the max attribute is specified and a value could be
parsed out of it, then the candidate maximum value is that value. Otherwise, the candidate
maximum value is 1.0.
If the candidate maximum value is greater than or equal to the minimum value, then the maximum value is the candidate maximum value. Otherwise, the maximum value is the same as the minimum value.
If the value attribute is specified and a value could
be parsed out of it, then that value is the candidate actual value. Otherwise, the candidate
actual value is zero.
If the candidate actual value is less than the minimum value, then the actual value is the minimum value.
Otherwise, if the candidate actual value is greater than the maximum value, then the actual value is the maximum value.
Otherwise, the actual value is the candidate actual value.
If the low attribute is specified and a value could be
parsed out of it, then the candidate low boundary is that value. Otherwise, the candidate low
boundary is the same as the minimum value.
If the candidate low boundary is less than the minimum value, then the low boundary is the minimum value.
Otherwise, if the candidate low boundary is greater than the maximum value, then the low boundary is the maximum value.
Otherwise, the low boundary is the candidate low boundary.
If the high attribute is specified and a value could be
parsed out of it, then the candidate high boundary is that value. Otherwise, the candidate high
boundary is the same as the maximum value.
If the candidate high boundary is less than the low boundary, then the high boundary is the low boundary.
Otherwise, if the candidate high boundary is greater than the maximum value, then the high boundary is the maximum value.
Otherwise, the high boundary is the candidate high boundary.
If the optimum attribute is specified and a value
could be parsed out of it, then the candidate optimum point is that value. Otherwise, the
candidate optimum point is the midpoint between the minimum value and the maximum value.
If the candidate optimum point is less than the minimum value, then the optimum point is the minimum value.
Otherwise, if the candidate optimum point is greater than the maximum value, then the optimum point is the maximum value.
Otherwise, the optimum point is the candidate optimum point.
All of which will result in the following inequalities all being true:
minimum value ≤ actual value ≤ maximum value
minimum value ≤ low boundary ≤ high boundary ≤ maximum value
minimum value ≤ optimum point ≤ maximum value
UA requirements for regions of the gauge: If the optimum point is equal to the low boundary or the high boundary, or anywhere in between them, then the region between the low and high boundaries of the gauge must be treated as the optimum region, and the low and high parts, if any, must be treated as suboptimal. Otherwise, if the optimum point is less than the low boundary, then the region between the minimum value and the low boundary must be treated as the optimum region, the region from the low boundary up to the high boundary must be treated as a suboptimal region, and the remaining region must be treated as an even less good region. Finally, if the optimum point is higher than the high boundary, then the situation is reversed; the region between the high boundary and the maximum value must be treated as the optimum region, the region from the high boundary down to the low boundary must be treated as a suboptimal region, and the remaining region must be treated as an even less good region.
UA requirements for showing the gauge: When representing a meter
element to the user, the UA should indicate the relative position of the actual value to the
minimum and maximum values, and the relationship between the actual value and the three regions of
the gauge.
User agents may combine the value of the title attribute and the other attributes to provide context-sensitive
help or inline text detailing the actual values.
The labels IDL attribute provides a list of the element's
labels.
fieldset elementSupport in all current engines.
Support in all current engines.
legend element, followed by flow content.disabled — Whether the descendant form controls, except any inside legend, are disabled
form — Associates the element with a form element
name — Name of the element to use in the form.elements API.The fieldset element represents a set of form controls (or other
content) grouped together, optionally with a caption. The caption is given by the first
legend element that is a child of the fieldset element, if any. The
remainder of the descendants form the group.
Element/fieldset#attr-disabled
Support in all current engines.
The form attribute is used to explicitly associate the
fieldset element with its form owner. The name attribute represents the element's name.
The willValidate, validity, and validationMessage attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the
constraint validation API. The form and name IDL attributes are part of the element's forms API.
legend elementSupport in all current engines.
Support in all current engines.
fieldset element.The legend element represents a caption for the rest of the contents
of the legend element's parent fieldset element, if
any.
The form IDL
attribute's behavior depends on whether the legend element is in a
fieldset element or not. If the legend has a fieldset
element as its parent, then the form IDL attribute must
return the same value as the form IDL attribute on that
fieldset element. Otherwise, it must return null.
A control's value is its internal state. As such, it might not match the user's current input.
The select element does not have a value;
the selectedness of its option
elements is what is used instead.
A form control can be designated as mutable.
A form-associated element has an associated parser inserted flag.
Support in all current engines.
Support in all current engines.
If a listed form-associated element has a
form attribute specified, then that attribute's value must be
the ID of a form element in the element's
tree.
When a form-associated element is created, its form owner must be initialized to null (no owner).
When a listed form-associated element's
form attribute is set, changed, or removed, then the user
agent must reset the form owner of that element.
When a listed form-associated element has a
form attribute and the ID of
any of the elements in the tree changes, then the user agent must reset the
form owner of that form-associated element.
When a listed form-associated element has a
form attribute and an element with an ID is inserted
into or removed from the
Document, then the user agent must reset the form owner of that
form-associated element.
Listed form-associated elements except for form-associated custom elements have a form IDL attribute, which, on getting, must return the
element's form owner, or null if there isn't one.
Support in all current engines.
Form-associated custom elements don't have
form IDL attribute. Instead, their
ElementInternals object has a form IDL attribute. On getting, it must throw a
"NotSupportedError" DOMException if the target element is not a form-associated custom
element. Otherwise, it must return the element's form owner, or null if there
isn't one.
name attributeSupport in all current engines.
The name IDL attribute must reflect the name content attribute.
dirname attributeSupport in all current engines.
The dirname
attribute on a form control element enables the submission of the directionality of
the element, and gives the name of the control that contains this value during form
submission. If such an attribute is specified, its value must not be the empty string.
maxlength attributeConstraint validation: If an element has a maximum allowed value length, its dirty value flag is true, its value was last changed by a user edit (as opposed to a change made by a script), and the length of the element's API value is greater than the element's maximum allowed value length, then the element is suffering from being too long.
User agents may prevent the user from causing the element's API value to be set to a value whose length is greater than the element's maximum allowed value length.
minlength attributeIf an element has both a maximum allowed value length and a minimum allowed value length, the minimum allowed value length must be smaller than or equal to the maximum allowed value length.
Constraint validation: If an element has a minimum allowed value length, its dirty value flag is true, its value was last changed by a user edit (as opposed to a change made by a script), its value is not the empty string, and the length of the element's API value is less than the element's minimum allowed value length, then the element is suffering from being too short.
disabled attributeSupport in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
A form control that is disabled must prevent any click events that are queued on the
user interaction task source from being dispatched on the element.
Constraint validation: If an element is disabled, it is barred from constraint validation.
Support in all current engines.
Support in all current engines.
The disabled IDL attribute must reflect the disabled content attribute.
Element/form#Attributes_for_form_submission
Support in all current engines.
The attributes for form submission that may be specified on form
elements are action, enctype, method, novalidate, and target.
The corresponding attributes for form submission that may be specified on submit buttons are formaction, formenctype, formmethod, formnovalidate, and formtarget. When omitted, they default to the values given on
the corresponding attributes on the form element.
Support in all current engines.
The action of an element is the value of the element's
formaction attribute, if the element is a submit button and has such an attribute, or the value of its
form owner's action attribute, if it has
one, or else the empty string.
Support in all current engines.
The method and
formmethod
content attributes are enumerated attributes with the
following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
get
| GET | Indicates the form will use the HTTP GET method.
|
post
| POST | Indicates the form will use the HTTP POST method.
|
dialog
| Dialog | Indicates the form is intended to close the dialog box in which
the form finds itself, if any, and otherwise not submit.
|
The method attribute's missing value default and invalid value default
are both the GET state.
The formmethod attribute has no missing value default, and its invalid value
default is the GET state.
The method of an element is one of those states. If the
element is a submit button and has a formmethod attribute, then the element's method is that attribute's state; otherwise, it is the form
owner's method attribute's state.
Support in all current engines.
The attribute's missing value default and invalid value default are both the application/x-www-form-urlencoded state.
The formenctype attribute has no missing value default, and its invalid value
default is the application/x-www-form-urlencoded state.
The enctype of an element is one of those three states.
If the element is a submit button and has a formenctype attribute, then the element's enctype is that attribute's state; otherwise, it is the
form owner's enctype attribute's state.
Support in all current engines.
The target and
formtarget
content attributes, if specified, must have values that are valid navigable target names or keywords.
Support in all current engines.
The no-validate state of an element is true if the
element is a submit button and the element's formnovalidate attribute is present, or if the element's
form owner's novalidate attribute is present,
and false otherwise.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
The action IDL
attribute must reflect the content attribute of the same name, except that on
getting, when the content attribute is missing or its value is the empty string, the element's
node document's URL must be returned
instead. The target
IDL attribute must reflect the content attribute of the same name. The method and enctype IDL attributes must
reflect the respective content attributes of the same name, limited to only
known values. The encoding IDL attribute must reflect the enctype content attribute, limited to only known
values. The noValidate IDL attribute must reflect the
novalidate content attribute. The formAction
IDL attribute must reflect the formaction
content attribute, except that on getting, when the content attribute is missing or its value is
the empty string, the element's node document's URL must be returned instead. The formEnctype IDL attribute must reflect the
formenctype content attribute, limited to only
known values. The formMethod IDL attribute must reflect the
formmethod content attribute, limited to only known
values. The formNoValidate IDL attribute must reflect
the formnovalidate content attribute. The formTarget IDL
attribute must reflect the formtarget
content attribute.
autocomplete attributeSupport in all current engines.
There are two ways this attribute is used. When wearing the autofill expectation
mantle, the autocomplete attribute describes what
input is expected from users. When wearing the autofill anchor mantle, the autocomplete attribute describes the meaning of the given
value.
On an input element whose type attribute is
in the state, the autocomplete attribute wears the autofill anchor
mantle. In all other cases, it wears the autofill expectation mantle.
When wearing the autofill expectation mantle, the autocomplete attribute, if specified, must have a value that
is an ordered set of space-separated tokens consisting of either a single token that
is an ASCII case-insensitive match for the string "off", or a single token that is an ASCII
case-insensitive match for the string "on",
or autofill detail tokens.
When wearing the autofill anchor
mantle, the autocomplete attribute, if specified, must have a value that is an ordered set of
space-separated tokens consisting of just autofill detail tokens (i.e. the
"on" and "off" keywords are not allowed).
As noted earlier, the meaning of the attribute and its keywords depends on the mantle that the attribute is wearing.
The autofill field listed above indicate that the user agent is allowed to provide the user with autocompletion values, and specifies what kind of value is expected. The meaning of each such keyword is described in the table below.
If the autocomplete attribute is omitted, the default
value corresponding to the state of the element's form owner's autocomplete attribute is used instead (either "on" or "off"). If there is no form owner, then the
value "on" is used.
The autofill field listed above indicate that the value of the particular kind of value specified is that value provided for this element. The meaning of each such keyword is described in the table below.
Some fields are only appropriate for certain form controls. An autofill field name is inappropriate for a control if the control does not belong to the group listed for that autofill field in the fifth column of the first row describing that autofill field in the table below. What controls fall into each group is described below the table.
| Field name | Meaning | Canonical Format | Canonical Format Example | Control group | |||
|---|---|---|---|---|---|---|---|
"name"
| Full name | Free-form text, no newlines | Sir Timothy John Berners-Lee, OM, KBE, FRS, FREng, FRSA | Text | |||
"honorific-prefix"
| Prefix or title (e.g. "Mr.", "Ms.", "Dr.", "Mlle") | Free-form text, no newlines | Sir | Text | |||
"given-name"
| Given name (in some Western cultures, also known as the first name) | Free-form text, no newlines | Timothy | Text | |||
"additional-name"
| Additional names (in some Western cultures, also known as middle names, forenames other than the first name) | Free-form text, no newlines | John | Text | |||
"family-name"
| Family name (in some Western cultures, also known as the last name or surname) | Free-form text, no newlines | Berners-Lee | Text | |||
"honorific-suffix"
| Suffix (e.g. "Jr.", "B.Sc.", "MBASW", "II") | Free-form text, no newlines | OM, KBE, FRS, FREng, FRSA | Text | |||
"nickname"
| Nickname, screen name, handle: a typically short name used instead of the full name | Free-form text, no newlines | Tim | Text | |||
"organization-title"
| Job title (e.g. "Software Engineer", "Senior Vice President", "Deputy Managing Director") | Free-form text, no newlines | Professor | Text | |||
"username"
| A username | Free-form text, no newlines | timbl | Username | |||
"new-password"
| A new password (e.g. when creating an account or changing a password) | Free-form text, no newlines | GUMFXbadyrS3 | Password | |||
"current-password"
| The current password for the account identified by the username field (e.g. when logging in)
| Free-form text, no newlines | qwerty | Password | |||
"one-time-code"
| One-time code used for verifying user identity | Free-form text, no newlines | 123456 | Password | |||
"organization"
| Company name corresponding to the person, address, or contact information in the other fields associated with this field | Free-form text, no newlines | World Wide Web Consortium | Text | |||
"street-address"
| Street address (multiple lines, newlines preserved) | Free-form text | 32 Vassar Street MIT Room 32-G524 | Multiline | |||
"address-line1"
| Street address (one line per field) | Free-form text, no newlines | 32 Vassar Street | Text | |||
"address-line2"
| Free-form text, no newlines | MIT Room 32-G524 | Text | ||||
"address-line3"
| Free-form text, no newlines | Text | |||||
"address-level4"
| The most fine-grained administrative level, in addresses with four administrative levels | Free-form text, no newlines | Text | ||||
"address-level3"
| The third administrative level, in addresses with three or more administrative levels | Free-form text, no newlines | Text | ||||
"address-level2"
| The second administrative level, in addresses with two or more administrative levels; in the countries with two administrative levels, this would typically be the city, town, village, or other locality within which the relevant street address is found | Free-form text, no newlines | Cambridge | Text | |||
"address-level1"
| The broadest administrative level in the address, i.e. the province within which the locality is found; for example, in the US, this would be the state; in Switzerland it would be the canton; in the UK, the post town | Free-form text, no newlines | MA | Text | |||
"country"
| Country code | Valid ISO 3166-1-alpha-2 country code [ISO3166] | US | Text | |||
"country-name"
| Country name | Free-form text, no newlines; derived from country in some cases
| US | Text | |||
"postal-code"
| Postal code, post code, ZIP code, CEDEX code (if CEDEX, append "CEDEX", and the arrondissement, if relevant, to the address-level2 field)
| Free-form text, no newlines | 02139 | Text | |||
"cc-name"
| Full name as given on the payment instrument | Free-form text, no newlines | Tim Berners-Lee | Text | |||
"cc-given-name"
| Given name as given on the payment instrument (in some Western cultures, also known as the first name) | Free-form text, no newlines | Tim | Text | |||
"cc-additional-name"
| Additional names given on the payment instrument (in some Western cultures, also known as middle names, forenames other than the first name) | Free-form text, no newlines | Text | ||||
"cc-family-name"
| Family name given on the payment instrument (in some Western cultures, also known as the last name or surname) | Free-form text, no newlines | Berners-Lee | Text | |||
"cc-number"
| Code identifying the payment instrument (e.g. the credit card number) | ASCII digits | 4114360123456785 | Text | |||
"cc-exp"
| Expiration date of the payment instrument | Valid month string | 2014-12 | Month | |||
"cc-exp-month"
| Month component of the expiration date of the payment instrument | Valid integer in the range 1..12 | 12 | Numeric | |||
"cc-exp-year"
| Year component of the expiration date of the payment instrument | Valid integer greater than zero | 2014 | Numeric | |||
"cc-csc"
| Security code for the payment instrument (also known as the card security code (CSC), card validation code (CVC), card verification value (CVV), signature panel code (SPC), credit card ID (CCID), etc.) | ASCII digits | 419 | Text | |||
"cc-type"
| Type of payment instrument | Free-form text, no newlines | Visa | Text | |||
"transaction-currency"
| The currency that the user would prefer the transaction to use | ISO 4217 currency code [ISO4217] | GBP | Text | |||
"transaction-amount"
| The amount that the user would like for the transaction (e.g. when entering a bid or sale price) | Valid floating-point number | 401.00 | Numeric | |||
"language"
| Preferred language | Valid BCP 47 language tag [BCP47] | en | Text | |||
"bday"
| Birthday | Valid date string | 1955-06-08 | Date | |||
"bday-day"
| Day component of birthday | Valid integer in the range 1..31 | 8 | Numeric | |||
"bday-month"
| Month component of birthday | Valid integer in the range 1..12 | 6 | Numeric | |||
"bday-year"
| Year component of birthday | Valid integer greater than zero | 1955 | Numeric | |||
"sex"
| Gender identity (e.g. Female, Fa'afafine) | Free-form text, no newlines | Male | Text | |||
"url"
| Home page or other web page corresponding to the company, person, address, or contact information in the other fields associated with this field | Valid URL string | https://www.w3.org/People/Berners-Lee/ | URL | |||
"photo"
| Photograph, icon, or other image corresponding to the company, person, address, or contact information in the other fields associated with this field | Valid URL string | https://www.w3.org/Press/Stock/Berners-Lee/2001-europaeum-eighth.jpg | URL | |||
"tel"
| Full telephone number, including country code | ASCII digits and U+0020 SPACE characters, prefixed by a U+002B PLUS SIGN character (+) | +1 617 253 5702 | Tel | |||
"tel-country-code"
| Country code component of the telephone number | ASCII digits prefixed by a U+002B PLUS SIGN character (+) | +1 | Text | |||
"tel-national"
| Telephone number without the county code component, with a country-internal prefix applied if applicable | ASCII digits and U+0020 SPACE characters | 617 253 5702 | Text | |||
"tel-area-code"
| Area code component of the telephone number, with a country-internal prefix applied if applicable | ASCII digits | 617 | Text | |||
"tel-local"
| Telephone number without the country code and area code components | ASCII digits | 2535702 | Text | |||
"tel-local-prefix"
| First part of the component of the telephone number that follows the area code, when that component is split into two components | ASCII digits | 253 | Text | |||
"tel-local-suffix"
| Second part of the component of the telephone number that follows the area code, when that component is split into two components | ASCII digits | 5702 | Text | |||
"tel-extension"
| Telephone number internal extension code | ASCII digits | 1000 | Text | |||
"email"
| Email address | Valid email address | timbl@w3.org | Username | |||
"impp"
| URL representing an instant messaging protocol endpoint (for example, "aim:goim?screenname=example" or "xmpp:fred@example.net")
| Valid URL string | irc://example.org/timbl,isuser | URL | |||
The groups correspond to controls as follows:
input elements with a type attribute in the Hidden state
input elements with a type attribute in the Text state
input elements with a type attribute in the Search state
textarea elements
select elements
input elements with a type attribute in the Hidden state
textarea elements
select elements
input elements with a type attribute in the Hidden state
input elements with a type attribute in the Text state
input elements with a type attribute in the Search state
input elements with a type attribute in the Password state
textarea elements
select elements
input elements with a type attribute in the Hidden state
input elements with a type attribute in the Text state
input elements with a type attribute in the Search state
input elements with a type attribute in the URL state
textarea elements
select elements
input elements with a type attribute in the Hidden state
input elements with a type attribute in the Text state
input elements with a type attribute in the Search state
input elements with a type attribute in the Email state
textarea elements
select elements
input elements with a type attribute in the Hidden state
input elements with a type attribute in the Text state
input elements with a type attribute in the Search state
input elements with a type attribute in the Telephone state
textarea elements
select elements
input elements with a type attribute in the Hidden state
input elements with a type attribute in the Text state
input elements with a type attribute in the Search state
input elements with a type attribute in the Number state
textarea elements
select elements
input elements with a type attribute in the Hidden state
input elements with a type attribute in the Text state
input elements with a type attribute in the Search state
input elements with a type attribute in the Month state
textarea elements
select elements
input elements with a type attribute in the Hidden state
input elements with a type attribute in the Text state
input elements with a type attribute in the Search state
input elements with a type attribute in the Date state
textarea elements
select elements
Address levels: The "address-level1" – "address-level4" fields are used to describe
the locality of the street address. Different locales have different numbers of levels. For
example, the US uses two levels (state and town), the UK uses one or two depending on the address
(the post town, and in some cases the locality), and China can use three (province, city,
district). The "address-level1" field
represents the widest administrative division. Different locales order the fields in different
ways; for example, in the US the town (level 2) precedes the state (level 1); while in Japan the
prefecture (level 1) precedes the city (level 2) which precedes the district (level 3). Authors
are encouraged to provide forms that are presented in a way that matches the country's conventions
(hiding, showing, and rearranging fields accordingly as the user changes the country).
Each input element to which the autocomplete attribute applies, each select element, and each textarea element, has an
autofill hint set, an autofill scope, an autofill field name, a
non-autofill credential type, and an IDL-exposed autofill value.
The autofill field name specifies the specific kind of data expected in the field,
e.g. "street-address" or "cc-exp".
The autofill hint set identifies what address or contact information type the user
agent is to look at, e.g. "shipping fax" or "billing".
The non-autofill credential type identifies a type of
credential that may be offered by the user agent when the
user interacts with the field alongside other autofill field values. If this value is
"webauthn" instead of null, selecting a credential of that type will resolve
a pending conditional mediation
navigator.credentials.get() request, instead of autofilling the field.
The autofill scope identifies the group of fields whose information concerns the
same subject, and consists of the autofill hint set with, if
applicable, the "section-*" prefix, e.g. "billing",
"section-parent shipping", or "section-child shipping
home".
These values are defined as the result of running the following algorithm:
If the element has no autocomplete attribute,
then jump to the step labeled default.
Let tokens be the result of splitting the attribute's value on ASCII whitespace.
If tokens is empty, then jump to the step labeled default.
Let index be the index of the last token in tokens.
Let field be the indexth token in tokens.
Set the category, maximum tokens pair to the result of determining a field's category given field.
If category is null, then jump to the step labeled default.
If the number of tokens in tokens is greater than maximum tokens, then jump to the step labeled default.
If category is Off or Automatic but the element's autocomplete attribute is wearing the autofill anchor
mantle, then jump to the step labeled default.
If category is Off, let the element's autofill field name
be the string "off", let its autofill hint set be empty, and
let its IDL-exposed autofill value be the string "off". Then,
return.
If category is Automatic, let the element's autofill field
name be the string "on", let its autofill hint set be
empty, and let its IDL-exposed autofill value be the string "on". Then, return.
Let scope tokens be an empty list.
Let hint tokens be an empty set.
Let credential type be null.
Let IDL value have the same value as field.
If category is Credential and the indexth token in tokens is
an ASCII case-insensitive match for "webauthn", then run the substeps that follow:
Set credential type to "webauthn".
If the indexth token in tokens is the first entry, then skip to the step labeled done.
Decrement index by one.
Set the category, maximum tokens pair to the result of determining a field's category given the indexth token in tokens.
If category is not Normal and category is not Contact, then jump to the step labeled default.
If index is greater than maximum tokens minus one (i.e. if the number of remaining tokens is greater than maximum tokens), then jump to the step labeled default.
Set IDL value to the concatenation of the indexth token in tokens, a U+0020 SPACE character, and the previous value of IDL value.
If the indexth token in tokens is the first entry, then skip to the step labeled done.
Decrement index by one.
If category is Contact and the indexth token in tokens is an ASCII case-insensitive match for one of the strings in the following list, then run the substeps that follow:
The substeps are:
Let contact be the matching string from the list above.
Insert contact at the start of scope tokens.
Add contact to hint tokens.
Let IDL value be the concatenation of contact, a U+0020 SPACE character, and the previous value of IDL value.
If the indexth entry in tokens is the first entry, then skip to the step labeled done.
Decrement index by one.
If the indexth token in tokens is an ASCII case-insensitive match for one of the strings in the following list, then run the substeps that follow:
The substeps are:
Let mode be the matching string from the list above.
Insert mode at the start of scope tokens.
Add mode to hint tokens.
Let IDL value be the concatenation of mode, a U+0020 SPACE character, and the previous value of IDL value.
If the indexth entry in tokens is the first entry, then skip to the step labeled done.
Decrement index by one.
If the indexth entry in tokens is not the first entry, then jump to the step labeled default.
If the first eight characters of the indexth token in tokens are not
an ASCII case-insensitive match for the string "section-", then jump to the step labeled
default.
Let section be the indexth token in tokens, converted to ASCII lowercase.
Insert section at the start of scope tokens.
Let IDL value be the concatenation of section, a U+0020 SPACE character, and the previous value of IDL value.
Done: Let the element's autofill hint set be hint tokens.
Let the element's non-autofill credential type be credential type.
Let the element's autofill scope be scope tokens.
Let the element's autofill field name be field.
Let the element's IDL-exposed autofill value be IDL value.
Return.
Default: Let the element's IDL-exposed autofill value be the empty string, and its autofill hint set and autofill scope be empty.
If the element's autocomplete attribute is
wearing the autofill anchor mantle, then let the element's autofill field
name be the empty string and return.
Let form be the element's form owner, if any, or null otherwise.
If form is not null and form's autocomplete attribute is in the off state, then let the element's
autofill field name be "off".
Otherwise, let the element's autofill field name be "on".
How to process the autofill hint set, autofill scope, and
autofill field name depends on the mantle that the autocomplete attribute is wearing.
When an element's autofill field name is "off", the user agent should not remember the control's
data, and should not offer past values to the user.
When an element's autofill field name is not "off", the user agent may store the control's
data, and may offer previously stored values to the user.
When the autofill field name is "on", the user agent should attempt to use heuristics to
determine the most appropriate values to offer the user, e.g. based on the element's name value, the position of the element in its tree,
what other fields exist in the form, and so forth.
When the autofill field name is one of the names of the autofill fields described above, the user agent should provide suggestions that match the meaning of the field name as given in the table earlier in this section. The autofill hint set should be used to select amongst multiple possible suggestions.
When the autofill field name is not the empty string, then the user agent must act as if the user had specified the control's data for the given autofill hint set, autofill scope, and autofill field name combination.
The "section-*" tokens in the autofill scope are opaque;
user agents must not attempt to derive meaning from the precise values of these tokens.
The autocompletion mechanism must be implemented by the user agent acting as if the user had modified the control's data, and must be done at a time where the element is mutable (e.g. just after the element has been inserted into the document, or when the user agent stops parsing). User agents must only prefill controls using values that the user could have entered.
A user agent prefilling a form control must not discriminate between form controls that are
in a document tree and those that are connected; that is, it is not
conforming to make the decision on whether or not to autofill based on whether the element's
root is a shadow root versus a Document.
A user agent prefilling a form control's value must not cause that control to suffer from a type mismatch, suffer from being too long, suffer from being too short, suffer from an underflow, suffer from an overflow, or suffer from a step mismatch. A user agent prefilling a form control's value must not cause that control to suffer from a pattern mismatch either. Where possible given the control's constraints, user agents must use the format given as canonical in the aforementioned table. Where it's not possible for the canonical format to be used, user agents should use heuristics to attempt to convert values so that they can be used.
A user agent may allow the user to override an element's autofill field name, e.g.
to change it from "off" to "on" to allow values to be remembered and prefilled despite
the page author's objections, or to always "off",
never remembering values.
More specifically, user agents may in particular consider replacing the autofill field
name of form controls that match the description given in the first column of the following
table, when their autofill field name is either "on" or "off", with the value given in the second cell of that
row. If this table is used, the replacements must be done in tree order, since all
but the first row references the autofill field name of earlier elements. When the
descriptions below refer to form controls being preceded or followed by others, they mean in the
list of listed elements that share the same form
owner.
| Form control | New autofill field name |
|---|---|
an input element whose type attribute is in
the Text state that is followed by an
input element whose type attribute is in
the Password state
|
"username"
|
an input element whose type attribute is in
the Password state that is preceded by an
input element whose autofill field name is "username"
|
"current-password"
|
an input element whose type attribute is in
the Password state that is preceded by an
input element whose autofill field name is "current-password"
|
"new-password"
|
an input element whose type attribute is in
the Password state that is preceded by an
input element whose autofill field name is "new-password"
|
"new-password"
|
The autocomplete IDL attribute, on getting, must return the
element's IDL-exposed autofill value, and on setting, must reflect the
content attribute of the same name.
The input and textarea elements define several attributes and methods
for handling their selection. Their shared algorithms are defined here.
Whenever the relevant value changes for an element to which these APIs apply, run these steps:
If the element has a selection:
If the start of the selection is now past the end of the relevant value, set it to the end of the relevant value.
If the end of the selection is now past the end of the relevant value, set it to the end of the relevant value.
If the user agent does not support empty selection, and both the start and end of the selection are now pointing to the end of the relevant value, then instead set the element's text entry cursor position to the end of the relevant value, removing any selection.
Otherwise, the element must have a text entry cursor position position. If it is now past the end of the relevant value, set it to the end of the relevant value.
Where possible, user interface features for changing the text selection in input and
textarea elements must be implemented using the set the selection range
algorithm so that, e.g., all the same events fire.
To set the selection direction of an element to a given direction, update the
element's selection direction to the given direction, unless the direction is "none" and the platform does not support that direction; in that case, update the
element's selection direction to "forward".
Support in all current engines.
The selectionStart attribute's setter
must run the following steps:
If this element is an input element, and selectionStart does
not apply to this element, throw an "InvalidStateError"
DOMException.
Let end be the value of this element's selectionEnd attribute.
If end is less than the given value, set end to the given value.
Set the selection range with the given value, end, and the value
of this element's selectionDirection
attribute.
The selectionEnd attribute's setter must
run the following steps:
If this element is an input element, and selectionEnd does not
apply to this element, throw an "InvalidStateError"
DOMException.
Set the selection range with the value of this element's selectionStart attribute, the given value, and
the value of this element's selectionDirection attribute.
The selectionDirection attribute's
setter must run the following steps:
If this element is an input element, and selectionDirection does not apply to this element, throw an
"InvalidStateError" DOMException.
Set the selection range with the value of this element's selectionStart attribute, the value of this
element's selectionEnd attribute, and the
given value.
The setRangeText() method uses the
following enumeration:
A submittable element is a candidate for constraint
validation except when a condition has barred
the element from constraint validation. (For example, an element is barred from
constraint validation if it has a datalist element ancestor.)
An element satisfies its constraints if it is not suffering from any of the above validity states.
The willValidate attribute's getter must return true, if
this element is a candidate for constraint validation, and false otherwise (i.e.,
false if any conditions are barring it from
constraint validation).
Support in all current engines.
The willValidate attribute of
ElementInternals interface, on getting, must throw a
"NotSupportedError" DOMException if the target element is not a form-associated custom
element. Otherwise, it must return true if the target
element is a candidate for constraint validation, and false otherwise.
HTMLInputElement/setCustomValidity
Support in all current engines.
Support in all current engines.
The validity attribute's getter must return a
ValidityState object that represents the validity states of this
element. This object is live.
Support in all current engines.
The validity attribute of
ElementInternals interface, on getting, must throw a
"NotSupportedError" DOMException if the target element is not a form-associated custom
element. Otherwise, it must return a ValidityState object that represents the
validity states of the target element. This
object is live.
A ValidityState object has the following attributes. On getting, they must return
true if the corresponding condition given in the following list is true, and false otherwise.
valueMissingThe control is suffering from being missing.
typeMismatchSupport in all current engines.
The control is suffering from a type mismatch.
patternMismatchSupport in all current engines.
The control is suffering from a pattern mismatch.
tooLongThe control is suffering from being too long.
tooShortThe control is suffering from being too short.
rangeUnderflowSupport in all current engines.
The control is suffering from an underflow.
rangeOverflowSupport in all current engines.
The control is suffering from an overflow.
stepMismatchSupport in all current engines.
The control is suffering from a step mismatch.
badInputThe control is suffering from bad input.
customErrorThe control is suffering from a custom error.
validNone of the other conditions are true.
The checkValidity() method, when invoked, must run the
check validity steps on this element.
ElementInternals/checkValidity
Support in all current engines.
The reportValidity() method, when invoked, must run the
report validity steps on this element.
ElementInternals/reportValidity
Support in all current engines.
Servers should not rely on client-side validation. Client-side validation can be intentionally bypassed by hostile users, and unintentionally bypassed by users of older user agents or automated tools that do not implement these features. The constraint validation features are only intended to improve the user experience, not to provide any kind of security mechanism.
This section is non-normative.
When a form is submitted, the data in the form is converted into the structure specified by the enctype, and then sent to the destination specified by the action using the given method.
For example, take the following form:
If the user types in "cats" in the first field and "fur" in the second, and then hits the
submit button, then the user agent will load /find.cgi?t=cats&q=fur.
On the other hand, consider this form:
Given the same user input, the result on submission is quite different: the user agent instead does an HTTP POST to the given URL, with as the entity body something like the following text:
------kYFrd4jNJEgCervE Content-Disposition: form-data; name="t" cats ------kYFrd4jNJEgCervE Content-Disposition: form-data; name="q" fur ------kYFrd4jNJEgCervE--
If the user agent supports letting the user submit a form implicitly (for example, on some
platforms hitting the "enter" key while a text control is focused implicitly submits
the form), then doing so for a form, whose default button has activation
behavior and is not disabled, must cause the user
agent to fire a click event at that default
button.
If the form has no submit button, then the implicit submission mechanism must perform the following steps:
If the form has more than one field that blocks implicit submission, then return.
Submit the form element from the
form element itself with userInvolvement set
to "activation".
For the purpose of the previous paragraph, an element is a field that blocks implicit
submission of a form element if it is an input element whose
form owner is that form element and whose type attribute is in one of the following states:
Text,
Search,
Telephone,
URL,
Email,
Password,
Date,
Month,
Week,
Time,
Local Date and Time,
Number
To submit a form element form
from an element submitter (typically a button), given an optional boolean submitted from submit() method (default false) and an optional
user navigation involvement userInvolvement (default "none"):
If form cannot navigate, then return.
If form's constructing entry list is true, then return.
Let form document be form's node document.
If form document's active sandboxing flag set has its sandboxed forms browsing context flag set, then return.
If submitted from submit() method is false,
then:
If form's firing submission events is true, then return.
Set form's firing submission events to true.
For each element field in the list of submittable elements whose form owner is form, set field's user validity to true.
If the submitter element's no-validate state is false, then interactively validate the constraints of form and examine the result. If the result is negative (i.e., the constraint validation concluded that there were invalid fields and probably informed the user of this), then:
Set form's firing submission events to false.
Return.
Let submitterButton be null if submitter is form. Otherwise, let submitterButton be submitter.
Let shouldContinue be the result of firing an
event named submit at form using
SubmitEvent, with the submitter
attribute initialized to submitterButton, the bubbles attribute initialized to true, and the cancelable attribute initialized to true.
Set form's firing submission events to false.
If shouldContinue is false, then return.
If form cannot navigate, then return.
Let encoding be the result of picking an encoding for the form.
Let entry list be the result of constructing the entry list with form, submitter, and encoding.
Assert: entry list is not null.
If form cannot navigate, then return.
Let method be the submitter element's method.
If method is dialog, then:
If form does not have an ancestor dialog element, then
return.
Let subject be form's nearest ancestor dialog
element.
Let result be null.
If submitter is an input element whose type attribute is in the Image Button state, then:
Let (x, y) be the selected coordinate.
Set result to the concatenation of x, ",", and y.
Otherwise, if submitter has a value, then set result to that value.
Close the dialog subject with result.
Return.
Let action be the submitter element's action.
If action is the empty string, let action be the URL of the form document.
Let parsed action be the result of encoding-parsing a URL given action, relative to submitter's node document.
If parsed action is failure, then return.
Let scheme be the scheme of parsed action.
Let enctype be the submitter element's enctype.
Let formTarget be null.
If the submitter element is a submit
button and it has a formtarget attribute, then
set formTarget to the formtarget attribute
value.
Let target be the result of getting an element's target given submitter's form owner and formTarget.
Let noopener be the result of getting an element's noopener with form, parsed action, and target.
Let targetNavigable be the first return value of applying the rules for choosing a navigable given target, form's node navigable, and noopener.
If targetNavigable is null, then return.
Let historyHandling be "auto".
If form document equals targetNavigable's active document, and form document has not yet
completely loaded, then set historyHandling to "replace".
Select the appropriate row in the table below based on scheme as given by the first cell of each row. Then, select the appropriate cell on that row based on method as given in the first cell of each column. Then, jump to the steps named in that cell and defined below the table.
| GET | POST | |
|---|---|---|
http
| Mutate action URL | Submit as entity body |
https
| Mutate action URL | Submit as entity body |
ftp
| Get action URL | Get action URL |
javascript
| Get action URL | Get action URL |
data
| Mutate action URL | Get action URL |
mailto
| Mail with headers | Mail as body |
If scheme is not one of those listed in this table, then the behavior is not defined by this specification. User agents should, in the absence of another specification defining this, act in a manner analogous to that defined in this specification for similar schemes.
Each form element has a planned navigation, which is either null or a
task; when the form is first created, its
planned navigation must be set to null. In the behaviors described below, when the
user agent is required to plan to navigate to a URL url given
an optional POST resource-or-null postResource (default null), it must
run the following steps:
Let referrerPolicy be the empty string.
If the form element's link types include the noreferrer keyword, then set referrerPolicy to "no-referrer".
If the form has a non-null planned navigation, remove it from
its task queue.
Queue an element task on the DOM manipulation task source given
the form element and the following steps:
Set the form's planned navigation to null.
Navigate targetNavigable to url
using the form element's node document, with historyHandling set to historyHandling, userInvolvement set to userInvolvement,
referrerPolicy set to referrerPolicy,
documentResource set to postResource, and formDataEntryList set to entry
list.
Set the form's planned navigation to the just-queued task.
The behaviors are as follows:
Let pairs be the result of converting to a list of name-value pairs with entry list.
Let query be the result of running the
application/x-www-form-urlencoded serializer with pairs
and encoding.
Set parsed action's query component to query.
Plan to navigate to parsed action.
Switch on enctype:
application/x-www-form-urlencodedLet pairs be the result of converting to a list of name-value pairs with entry list.
Let body be the result of running the
application/x-www-form-urlencoded serializer with pairs
and encoding.
Set body to the result of encoding body.
Let mimeType be `application/x-www-form-urlencoded`.
multipart/form-dataLet body be the result of running the multipart/form-data encoding algorithm with entry list
and encoding.
Let mimeType be the isomorphic
encoding of the concatenation of "multipart/form-data; boundary=" and the multipart/form-data boundary string generated by the multipart/form-data encoding algorithm.
text/plainLet pairs be the result of converting to a list of name-value pairs with entry list.
Let body be the result of running the text/plain
encoding algorithm with pairs.
Set body to the result of encoding body using encoding.
Let mimeType be `text/plain`.
Plan to navigate to parsed action given a POST resource whose request body is body and request content-type is mimeType.
Plan to navigate to parsed action.
Let pairs be the result of converting to a list of name-value pairs with entry list.
Let headers be the result of running the
application/x-www-form-urlencoded serializer with pairs
and encoding.
Replace occurrences of U+002B PLUS SIGN characters (+) in headers with
the string "%20".
Set parsed action's query to headers.
Plan to navigate to parsed action.
Let pairs be the result of converting to a list of name-value pairs with entry list.
Switch on enctype:
text/plainLet body be the result of running the text/plain
encoding algorithm with pairs.
Set body to the result of running UTF-8 percent-encode on body using the default encode set. [URL]
Let body be the result of running the
application/x-www-form-urlencoded serializer with pairs
and encoding.
If parsed action's query is null, then set it to the empty string.
If parsed action's query is not the empty string, then append a single U+0026 AMPERSAND character (&) to it.
Append "body=" to parsed action's query.
Append body to parsed action's query.
Plan to navigate to parsed action.
An entry list is a list of entries, typically representing the contents of a form. An entry is a tuple consisting of a name (a scalar value string) and a value (either a scalar value
string or a File object).
The application/x-www-form-urlencoded and text/plain encoding algorithms take a list of name-value pairs, where the values
must be strings, rather than an entry list where the value can be a
File. The following algorithm performs the conversion.
See URL for details
on application/x-www-form-urlencoded. [URL]
For details on how to interpret multipart/form-data payloads, see RFC 7578.
[RFC7578]
Payloads using the text/plain format are intended to be human readable. They are
not reliably interpretable by computer, as the format is ambiguous (for example, there is no way
to distinguish a literal newline in a value from the newline at the end of the value).
SubmitEvent interfaceSupport in all current engines.
Support in all current engines.
The submitter attribute must return the value it was
initialized to.
FormDataEvent interfaceSupport in all current engines.
Support in all current engines.
The formData attribute must return the value it was
initialized to. It represents a FormData object associated to the entry
list that is constructed when the
form is submitted.
Each resettable element defines its own reset algorithm. Changes made to form controls as part of
these algorithms do not count as changes caused by the user (and thus, e.g., do not cause input events to fire).
details elementSupport in all current engines.
Support in all current engines.
summary element followed by flow content.name — Name of group of mutually-exclusive details elements
open — Whether the details are visible
The details element represents a disclosure widget from which the
user can obtain additional information or controls.
The first summary element child of the element, if any,
represents the summary or legend of the details. If there is no
child summary element, the user agent should provide its own legend (e.g.
"Details").
The rest of the element's contents represents the additional information or controls.
Before using this feature, authors should consider whether this grouping of related
details elements into an exclusive accordion is helpful or harmful to users.
While using an exclusive accordion can reduce the maximum amount of space that a set of content
can occupy, it can also frustrate users who have to open many items to find what they want or
users who want to look at the contents of multiple items at the same time.
A document must not contain more than one details element in the same
details name group that has the open
attribute present. Authors must not use script to add details elements to a document
in a way that would cause a details name group to have more than one
details element with the open attribute
present.
A document must not contain a details element that is a descendant of another
details element in the same details name group.
Documents that use the name attribute to group multiple
related details elements should keep those related elements together in a containing
element (such as a section element or article element). When it makes
sense for the group to be introduced with a heading, authors should put that heading in a heading element at the start of the containing element.
When the element is created, if the attribute is absent, the additional information should be hidden; if the attribute is present, that information should be shown. Subsequently, if the attribute is removed, then the information should be hidden; if the attribute is added, the information should be shown.
The user agent should allow the user to request that the additional information be shown or
hidden. To honor a request for the details to be shown, the user agent must set the open attribute on the element to the empty string. To honor a
request for the information to be hidden, the user agent must remove the open attribute from the element.
The following attribute change
steps, given element, localName, oldValue,
value, and namespace, are used for all details elements:
If namespace is not null, then return.
If localName is name, then ensure
details exclusivity by closing the given element if needed given
element.
If localName is open, then:
If oldValue is null and value is not null, then ensure details exclusivity by closing other elements if needed given element.
The details HTML element insertion
steps, given insertedNode, are:
Ensure details exclusivity by closing the given element if needed given insertedNode.
Support in all current engines.
summary elementSupport in all current engines.
details element.HTMLElement.The summary element represents a summary, caption, or legend for the
rest of the contents of the summary element's parent details
element, if any.
The activation behavior of summary elements is to run the following
steps:
If this summary element is not the summary for its parent
details, then return.
Let parent be this summary element's parent.
If the open attribute is present on
parent, then remove it.
Otherwise, set parent's
open attribute to the empty string.
User agents may expose the commands that match the following criteria:
The facet is false (visible)
The element is in a document with a non-null browsing context.
Neither the element nor any of its ancestors has a attribute specified.
User agents are encouraged to do this especially for commands that have Access Keys, as a way to advertise those keys to the user.
An a element with an href attribute defines a command.
The Label of the command is the element's descendant text content.
The Access Key of the command is the element's assigned access key, if any.
The of the command is true (hidden) if the element has a attribute, and false otherwise.
The Disabled State facet of the command is true if the element or one of its ancestors is inert, and false otherwise.
The Action of the command is to fire a click event at the element.
A button element always defines a
command.
The Label, Access Key, , and Action facets of the command are determined as for a elements (see the previous section).
The Disabled State of the command is true if the element or one of its ancestors is inert, or if the element's disabled state is set, and false otherwise.
An input element whose type attribute is in
one of the Submit Button, Reset Button, Image
Button, Button, Radio Button, or Checkbox states defines a
command.
The Label of the command is determined as follows:
If the type attribute is in one of the
Submit Button, Reset Button, Image
Button, or Button states, then the
Label is the string given by the
value attribute, if any, and a UA-dependent,
locale-dependent value that the UA uses to label the button itself if the attribute is
absent.
Otherwise, if the element is a labeled control, then the Label is the descendant text content of the
first label element in tree order whose labeled control
is the element in question. (In JavaScript terms, this is given by element.labels[0].textContent.)
Otherwise, if the value attribute is present, then
the Label is the value of that attribute.
Otherwise, the Label is the empty string.
The Access Key of the command is the element's assigned access key, if any.
The of the command is true (hidden) if the element has a attribute, and false otherwise.
The Disabled State of the command is true if the element or one of its ancestors is inert, or if the element's disabled state is set, and false otherwise.
The Action of the command is to fire a click event at the element.
An option element with an ancestor select element and either no value attribute or a value
attribute that is not the empty string defines a command.
The Label of the command is the value of the
option element's label attribute, if there is
one, or else the option element's descendant text content, with ASCII whitespace stripped and collapsed.
The Access Key of the command is the element's assigned access key, if any.
The of the command is true (hidden) if the element has a attribute, and false otherwise.
The Disabled State of the command is true if
the element is disabled, or if its nearest ancestor
select element is disabled, or if it or one
of its ancestors is inert, and false otherwise.
If the option's nearest ancestor select element has a multiple attribute, the Action of the command is to toggle the option element. Otherwise, the Action is to pick the option element.
A legend element defines a command if all of
the following are true:
It has an assigned access key.
It is a child of a fieldset element.
The Label of the command is the element's descendant text content.
The Access Key of the command is the element's assigned access key.
The , Disabled State, and Action facets of the command are the same as the respective
facets of the legend element's accesskey delegatee.
An element that has an assigned access key defines a command.
If one of the earlier sections that define elements that define commands define that this element defines a command, then that section applies to this element, and this section does not. Otherwise, this section applies to that element.
The Label of the command depends on the element. If
the element is a labeled control, the descendant text content of the
first label element in tree order whose labeled control is
the element in question is the Label (in JavaScript
terms, this is given by element.labels[0].textContent).
Otherwise, the Label is the element's descendant
text content.
The Access Key of the command is the element's assigned access key.
The of the command is true (hidden) if the element has a attribute, and false otherwise.
The Disabled State of the command is true if the element or one of its ancestors is inert, and false otherwise.
The Action of the command is to run the following steps:
click event at the element.dialog elementSupport in all current engines.
Support in all current engines.
closedby — Which user actions will close the dialog
open — Whether the dialog box is showing
The dialog element represents a transitory part of an application, in the form of
a small window ("dialog box"), which the user interacts with to perform a task or gather
information. Once the user is done, the dialog can be automatically closed by the application, or
manually closed by the user.
Especially for modal dialogs, which are a familiar pattern across all types of applications, authors should work to ensure that dialogs in their web applications behave in a way that is familiar to users of non-web applications.
An important part of user-facing dialog behavior is the placement of initial focus. The
dialog focusing steps attempt to pick a good candidate for initial focus when a
dialog is shown, but might not be a substitute for authors carefully thinking through the correct
choice to match user expectations for a specific dialog. As such, authors should use the autofocus attribute on the descendant element of the dialog that
the user is expected to immediately interact with after the dialog opens. If there is no such
element, then authors should use the autofocus attribute
on the dialog element itself.
Another important aspect of user behavior is whether dialogs are scrollable or not. In some cases, overflow (and thus scrollability) cannot be avoided, e.g., when it is caused by the user's high text zoom settings. But in general, scrollable dialogs are not expected by users. Adding large text nodes directly to dialog elements is particularly bad as this is likely to cause the dialog element itself to overflow. Authors are best off avoiding them.
The closedby
content attribute is an enumerated attribute with the following keywords and
states:
| Keyword | State | Brief description |
|---|---|---|
any
| Any | Close requests or clicks outside close the dialog. |
closerequest
| Close Request | Close requests close the dialog. |
none
| None | No user actions automatically close the dialog. |
A dialog element without an open attribute
specified should not be shown to the user. This requirement may be implemented indirectly through
the style layer. For example, user agents that support the suggested
default rendering implement this requirement using the CSS rules described in the Rendering section.
The tabindex attribute must not be specified on
dialog elements.
The dialog HTML element removing steps, given removedNode
and oldParent, are:
If removedNode's close watcher is not null, then:
Destroy removedNode's close watcher.
Set removedNode's close watcher to null.
If removedNode's node document's top layer contains removedNode, then remove an element from the top layer immediately given removedNode.
Set is modal of removedNode to false.
Remove removedNode from removedNode's node document's open dialogs list.
The returnValue IDL attribute, on getting, must return
the last value to which it was set. On setting, it must be set to the new value. When the element
is created, it must be set to the empty string.
Each HTML element has a previously focused
element which is null or an element, and it is initially null. When showModal() and show()
are called, this element is set to the currently focused element before running the
dialog focusing steps. Elements with the popover
attribute set this element to the currently focused element during the show popover algorithm.
The closedBy IDL attribute must reflect the
closedby content attribute, limited to only
known values.
Support in all current engines.
The open IDL
attribute must reflect the open content
attribute.
Scripts allow authors to add interactivity to their documents.
Authors are encouraged to use declarative alternatives to scripting where possible, as declarative mechanisms are often more maintainable, and many users disable scripting.
Authors are also encouraged to make their applications degrade gracefully in the absence of scripting support.
script elementSupport in all current engines.
Support in all current engines.
src
attribute, depends on the value of the type attribute, but must match
script content restrictions.src
attribute, the element must be either empty or contain only
script documentation that also matches script
content restrictions.src — Address of the resource
type — Type of script
nomodule — Prevents execution in user agents that support module scripts
async — Execute script when available, without blocking while fetching
defer — Defer script execution
crossorigin — How the element handles crossorigin requests
integrity — Integrity metadata used in Subresource Integrity checks [SRI]
referrerpolicy — Referrer policy for fetches initiated by the element
blocking — Whether the element is potentially render-blocking
fetchpriority — Sets the priority for fetches initiated by the element
The script element allows authors to include dynamic script and data blocks in
their documents. The element does not represent content for the
user.
Support in all current engines.
The contents of inline script elements, or the external script resource, must
conform with the requirements of the JavaScript specification's Script or Module productions, for classic scripts and JavaScript module scripts respectively. [JAVASCRIPT]
The contents of the external script resource for CSS module scripts must conform to the requirements of the CSS specification. [CSS]
The contents of the external script resource for JSON module scripts must conform to the requirements of the JSON specification. [JSON]
The contents of inline script elements for import
maps must conform with the import map authoring requirements.
For import map script elements, the src, async, nomodule, defer,
crossorigin, integrity, and referrerpolicy attributes must not be specified.
A document must not have more than one import map script element.
When used to include data blocks, the data must be embedded
inline, the format of the data must be given using the type
attribute, and the contents of the script element must conform to the requirements
defined for the format used. The src, async, nomodule,
defer, crossorigin, integrity, referrerpolicy, and fetchpriority attributes must not be specified.
The nomodule
attribute is a boolean attribute that prevents a script from being executed in user
agents that support module scripts. This allows selective
execution of module scripts in modern user agents and classic scripts in older user agents, as shown below. The nomodule attribute must not be specified on module scripts (and will be ignored if it is).
Support in all current engines.
Support in all current engines.
There are several possible modes that can be selected using these attributes, and depending on the script's type.
For classic scripts, if the async attribute is present, then the classic script will be
fetched in parallel to parsing and evaluated as soon as it is available (potentially
before parsing completes). If the async attribute is not
present but the defer attribute is present, then the
classic script will be fetched in parallel and evaluated when the page has finished
parsing. If neither attribute is present, then the script is fetched and evaluated immediately,
blocking parsing until these are both complete.
For module scripts, if the async attribute is present, then the module script and all its
dependencies will be fetched in parallel to parsing, and the module script will
be evaluated as soon as it is available (potentially before parsing completes). Otherwise, the
module script and its dependencies will be fetched in parallel to parsing and
evaluated when the page has finished parsing. (The defer
attribute has no effect on module scripts.)
This is all summarized in the following schematic diagram:
The defer attribute may be specified even if the async attribute is specified, to cause legacy web browsers that
only support defer (and not async) to fall back to the defer behavior instead of the blocking behavior that
is the default.
Changing the src, type, nomodule, async, defer, crossorigin, integrity, referrerpolicy, and fetchpriority attributes dynamically has no direct
effect; these attributes are only used at specific times described below.
The IDL attributes src, type, defer, integrity, and blocking, must each
reflect the respective content attributes of the same name.
HTMLScriptElement/referrerPolicy
Support in all current engines.
The async setter steps are:
Set this's force async to false.
If the given value is true, then set this's async content attribute to the empty string.
The text attribute's setter must string replace
all with the given value within this script element.
HTMLScriptElement/supports_static
Support in all current engines.
A script element has several associated pieces of state.
A script element has a parser document, which is either null or a
Document, initially null. It is set by the HTML parser and the
XML parser on script elements they insert, and affects the processing
of those elements. script elements with non-null parser documents are known as parser-inserted.
A script element has steps to run when the result
is ready, which are a series of steps or null, initially null. To mark as ready a
script element el given a script, import map parse result, or null
result:
Set el's result to result.
If el's steps to run when the result is ready are not null, then run them.
Set el's steps to run when the result is ready to null.
Set el's delaying the load event to false.
A script element el is implicitly potentially
render-blocking if el's type is
"classic", el is parser-inserted, and
el does not have an async or defer attribute.
The cloning steps for script
elements given node, copy, and subtree are to set
copy's already started to node's already
started.
When an async attribute is added to a
script element el, the user agent must set el's
force async to false.
Whenever a script element el's delaying the load event is true, the user agent must
delay the load event of el's preparation-time document.
The script HTML element post-connection steps, given
insertedNode, are:
If insertedNode is not connected, then return.
If insertedNode is parser-inserted, then return.
Prepare the script element given insertedNode.
The script children changed steps are:
Run the script HTML element post-connection steps, given the
script element.
The following attribute change
steps, given element, localName, oldValue,
value, and namespace, are used for all script elements:
If namespace is not null, then return.
If localName is src, then run the
script HTML element post-connection steps, given
element.
User agents are not required to support JavaScript. This standard needs to be updated
if a language other than JavaScript comes along and gets similar wide adoption by web browsers.
Until such a time, implementing other languages is in conflict with this standard, given the
processing model defined for the script element.
Servers should use text/javascript for JavaScript resources, in accordance with
Updates to ECMAScript Media Types. Servers should not use other
JavaScript MIME types for JavaScript resources, and
must not use non-JavaScript MIME types.
[RFC9239]
For external JavaScript resources, MIME type parameters in `Content-Type` headers
are generally ignored. (In some cases the `charset` parameter has an
effect.) However, for the script element's type attribute they are significant; it uses the JavaScript
MIME type essence match concept.
Furthermore, again for external JavaScript resources, special considerations apply around
`Content-Type` header processing as detailed in the prepare the script
element algorithm and Fetch. [FETCH]
The script element's descendant text content must match the script production in the following ABNF, the character set for which is Unicode.
[ABNF]
script = outer * ( comment-open inner comment-close outer )
outer = < any string that doesn 't contain a substring that matches not-in-outer >
not-in-outer = comment-open
inner = < any string that doesn 't contain a substring that matches not-in-inner >
not-in-inner = comment-close / script-open
comment-open = "<!--"
comment-close = "-->"
script-open = "<" s c r i p t tag-end
s = %x0053 ; U+0053 LATIN CAPITAL LETTER S
s =/ %x0073 ; U+0073 LATIN SMALL LETTER S
c = %x0043 ; U+0043 LATIN CAPITAL LETTER C
c =/ %x0063 ; U+0063 LATIN SMALL LETTER C
r = %x0052 ; U+0052 LATIN CAPITAL LETTER R
r =/ %x0072 ; U+0072 LATIN SMALL LETTER R
i = %x0049 ; U+0049 LATIN CAPITAL LETTER I
i =/ %x0069 ; U+0069 LATIN SMALL LETTER I
p = %x0050 ; U+0050 LATIN CAPITAL LETTER P
p =/ %x0070 ; U+0070 LATIN SMALL LETTER P
t = %x0054 ; U+0054 LATIN CAPITAL LETTER T
t =/ %x0074 ; U+0074 LATIN SMALL LETTER T
tag-end = %x0009 ; U+0009 CHARACTER TABULATION (tab)
tag-end =/ %x000A ; U+000A LINE FEED (LF)
tag-end =/ %x000C ; U+000C FORM FEED (FF)
tag-end =/ %x0020 ; U+0020 SPACE
tag-end =/ %x002F ; U+002F SOLIDUS (/)
tag-end =/ %x003E ; U+003E GREATER-THAN SIGN (>)
When a script element contains script documentation, there are
further restrictions on the contents of the element, as described in the section below.
If a script element's src attribute is
specified, then the contents of the script element, if any, must be such that the
value of the text IDL attribute, which is derived from the
element's contents, matches the documentation production in the following
ABNF, the character set for which is Unicode. [ABNF]
documentation = * ( * ( space / tab / comment ) [ line-comment ] newline )
comment = slash star * ( not-star / star not-slash ) 1* star slash
line-comment = slash slash * not-newline
; characters
tab = %x0009 ; U+0009 CHARACTER TABULATION (tab)
newline = %x000A ; U+000A LINE FEED (LF)
space = %x0020 ; U+0020 SPACE
star = %x002A ; U+002A ASTERISK (*)
slash = %x002F ; U+002F SOLIDUS (/)
not-newline = %x0000-0009 / %x000B-10FFFF
; a scalar value other than U+000A LINE FEED (LF)
not-star = %x0000-0029 / %x002B-10FFFF
; a scalar value other than U+002A ASTERISK (*)
not-slash = %x0000-002E / %x0030-10FFFF
; a scalar value other than U+002F SOLIDUS (/)
script elements and XSLTThis section is non-normative.
This specification does not define how XSLT interacts with the script element.
However, in the absence of another specification actually defining this, here are some guidelines
for implementers, based on existing implementations:
When an XSLT transformation program is triggered by an <?xml-stylesheet?> processing instruction and the browser implements a
direct-to-DOM transformation, script elements created by the XSLT processor need to
have its parser document set correctly, and run in document order (modulo scripts
marked defer or async), immediately, as the transformation is
occurring.
The XSLTProcessor transformToDocument() method adds elements
to a Document object with a null browsing
context, and, accordingly, any script elements they create need to have
their already started set to true in the prepare the script element
algorithm and never get executed (scripting is
disabled). Such script elements still need to have their parser
document set, though, such that their async IDL
attribute will return false in the absence of an async
content attribute.
The XSLTProcessor transformToFragment() method needs to
create a fragment that is equivalent to one built manually by creating the elements using document.createElementNS(). For instance, it needs
to create script elements with null parser document and with their
already started set to false, so that they will execute when the fragment is
inserted into a document.
The main distinction between the first two cases and the last case is that the first two
operate on Documents and the last operates on a fragment.
noscript elementSupport in all current engines.
head element of an HTML document, if there are no ancestor noscript elements.noscript elements.head element: in any order, zero or more link elements, zero or more style elements, and zero or more meta elements.head element: transparent, but there must be no noscript element descendants.HTMLElement.The noscript element represents nothing if scripting is enabled, and represents its children if
scripting is disabled. It is used to present different
markup to user agents that support scripting and those that don't support scripting, by affecting
how the document is parsed.
When used in HTML documents, the allowed content model is as follows:
head element, if scripting is
disabled for the noscript elementThe noscript element must contain only link, style,
and meta elements.
head element, if scripting is enabled
for the noscript elementThe noscript element must contain only text, except that invoking the
HTML fragment parsing algorithm with
the noscript element as the context
element and the text contents as the input must result in a list of nodes
that consists only of link, style, and meta elements that
would be conforming if they were children of the noscript element, and no parse errors.
head elements, if scripting is
disabled for the noscript elementThe noscript element's content model is transparent, with the
additional restriction that a noscript element must not have a noscript
element as an ancestor (that is, noscript can't be nested).
head elements, if scripting is
enabled for the noscript elementThe noscript element must contain only text, except that the text must be such
that running the following algorithm results in a conforming document with no
noscript elements and no script elements, and such that no step in the
algorithm throws an exception or causes an HTML parser to flag a parse
error:
script element from the document.noscript element in the document. For every
noscript element in that list, perform the following steps:
noscript
element.outerHTML attribute of the
noscript element to the value of s. (This, as a side-effect, causes
the noscript element to be removed from the document.)The noscript element must not be used in XML documents.
The noscript element has no other requirements. In particular, children of the
noscript element are not exempt from form submission, scripting, and so
forth, even when scripting is enabled for the element.
template elementSupport in all current engines.
Support in all current engines.
colgroup element that doesn't have a span attribute.shadowrootmode — Enables streaming declarative shadow roots
shadowrootdelegatesfocus — Sets delegates focus on a declarative shadow root
shadowrootclonable — Sets clonable on a declarative shadow root
shadowrootserializable — Sets serializable on a declarative shadow root
The template element is used to declare fragments of HTML that can be cloned and
inserted in the document by script.
In a rendering, the template element represents nothing.
The shadowrootmode content attribute is an
enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
open
| open | The template element represents an open declarative shadow root. |
closed
| closed | The template element represents a closed declarative shadow root. |
The template contents of a template element are not children of the element itself.
The adopting steps
(with node and oldDocument as parameters) for template elements
are the following:
Let doc be node's node document's appropriate template contents owner document.
Adopt node's
template contents (a DocumentFragment object) into doc.
The shadowRootSerializable IDL attribute
must reflect the shadowrootserializable content attribute.
The cloning steps for template
elements given node, copy, and subtree are:
If subtree is false, then return.
For each child of node's template contents's children, in tree order: clone a node given child with document set to copy's template contents's node document, subtree set to true, and parent set to copy's template contents.
template elements with XSLT and XPathThis section is non-normative.
This specification does not define how XSLT and XPath interact with the template
element. However, in the absence of another specification actually defining this, here are some
guidelines for implementers, which are intended to be consistent with other processing described
in this specification:
An XSLT processor based on an XML parser that acts as described
in this specification needs to act as if template elements contain as
descendants their template contents for the purposes of the transform.
An XSLT processor that outputs a DOM needs to ensure that nodes that would go into a
template element are instead placed into the element's template
contents.
XPath evaluation using the XPath DOM API when applied to a Document parsed
using the HTML parser or the XML parser described in this specification
needs to ignore template contents.
slot elementSupport in all current engines.
Support in all current engines.
name — Name of shadow tree slot
The slot element defines a slot. It is
typically used in a shadow tree. A slot element represents
its assigned nodes, if any, and its contents otherwise.
Support in all current engines.
canvas elementSupport in all current engines.
Support in all current engines.
a elements, img elements with
usemap attributes, button elements,
input elements whose type attribute are in
the Checkbox or Radio Button states, input elements that are
buttons, and select elements with a multiple attribute or a display size greater than 1.width — Horizontal dimension
height — Vertical dimension
The canvas element provides scripts with a resolution-dependent bitmap canvas,
which can be used for rendering graphs, game graphics, art, or other visual images on the fly.
Authors should not use the canvas element in a document when a more suitable
element is available. For example, it is inappropriate to use a canvas element to
render a page heading: if the desired presentation of the heading is graphically intense, it
should be marked up using appropriate elements (typically h1) and then styled using
CSS and supporting technologies such as shadow trees.
When authors use the canvas element, they must also provide content that, when
presented to the user, conveys essentially the same function or purpose as the
canvas's bitmap. This content may be placed as content of the canvas
element. The contents of the canvas element, if any, are the element's fallback
content.
In interactive visual media, if scripting is enabled for
the canvas element, and if support for canvas elements has been enabled,
then the canvas element represents embedded content
consisting of a dynamically created image, the element's bitmap.
In non-interactive, static, visual media, if the canvas element has been
previously associated with a rendering context (e.g. if the page was viewed in an interactive
visual medium and is now being printed, or if some script that ran during the page layout process
painted on the element), then the canvas element represents
embedded content with the element's current bitmap and size. Otherwise, the element
represents its fallback content instead.
In non-visual media, and in visual media if scripting is
disabled for the canvas element or if support for canvas elements
has been disabled, the canvas element represents its fallback
content instead.
When a canvas element represents embedded content, the
user can still focus descendants of the canvas element (in the fallback
content). When an element is focused, it is the target of keyboard interaction
events (even though the element itself is not visible). This allows authors to make an interactive
canvas keyboard-accessible: authors should have a one-to-one mapping of interactive regions to focusable areas in the fallback content. (Focus has no
effect on mouse interaction events.) [UIEVENTS]
An element whose nearest canvas element ancestor is being rendered
and represents embedded content is an element that is being used as
relevant canvas fallback content.
The canvas element has two attributes to control the size of the element's bitmap:
width and height. These attributes,
when specified, must have values that are valid
non-negative integers. The rules for parsing non-negative
integers must be used to obtain their numeric
values. If an attribute is missing, or if parsing its value returns an error, then the
default value must be used instead. The width
attribute defaults to 300, and the height attribute
defaults to 150.
When setting the value of the width or height attribute, if the context mode of the canvas
element is set to placeholder, the
user agent must throw an "InvalidStateError" DOMException
and leave the attribute's value unchanged.
The natural dimensions of the canvas element when it
represents embedded content are equal to the dimensions of the
element's bitmap.
The user agent must use a square pixel density consisting of one pixel of image data per
coordinate space unit for the bitmaps of a canvas and its rendering contexts.
When its canvas context mode is none, a canvas element has no rendering context,
and its bitmap must be transparent black with a natural width equal
to the numeric value of the element's width attribute and a natural height equal to
the numeric value of the element's height attribute, those values being interpreted in CSS pixels, and being updated as the attributes are set, changed, or
removed.
When its canvas context mode is placeholder, a canvas element has no
rendering context. It serves as a placeholder for an OffscreenCanvas object, and
the content of the canvas element is updated by the OffscreenCanvas
object's rendering context.
When a canvas element represents embedded content, it provides a
paint source whose width is the element's natural width, whose height
is the element's natural height, and whose appearance is the element's bitmap.
Whenever the width and height content attributes are set, removed, changed, or
redundantly set to the value they already have, then the user agent must perform the action
from the row of the following table that corresponds to the canvas element's context mode.
|
Action | |
|---|---|
|
Follow the steps to set bitmap
dimensions to the numeric values
of the | |
|
Follow the behavior defined in the WebGL specifications. [WEBGL] | |
|
Follow the behavior defined in WebGPU. [WEBGPU] | |
|
If the context's bitmap
mode is set to blank,
run the steps to set an | |
|
Do nothing. | |
|
Do nothing. |
Support in all current engines.
Support in all current engines.
The width
and height
IDL attributes must reflect the respective content attributes of the same name, with
the same defaults.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
The CanvasRenderingContext2D 2D rendering context represents a flat linear
Cartesian surface whose origin (0,0) is at the top left corner, with the coordinate space having
x values increasing when going right, and y values increasing when going
down. The x-coordinate of the right-most edge is equal to the width of the rendering
context's output bitmap in CSS pixels; similarly, the
y-coordinate of the bottom-most edge is equal to the height of the rendering context's
output bitmap in CSS pixels.
The size of the coordinate space does not necessarily represent the size of the actual bitmaps that the user agent will use internally or during rendering. On high-definition displays, for instance, the user agent may internally use bitmaps with four device pixels per unit in the coordinate space, so that the rendering remains at high quality throughout. Anti-aliasing can similarly be implemented using oversampling with bitmaps of a higher resolution than the final image on the display.
The canvas attribute must return the value it was
initialized to when the object was created.
The PredefinedColorSpace enumeration is used to specify the color space of the canvas's backing store.
The "display-p3" value indicates the
'display-p3' color space.
If a point is not outside a shape, it is inside the shape.
The ImageSmoothingQuality enumeration is used to express a preference for the
interpolation quality to use when smoothing images.
The "high" value indicates a preference
for a high level of image interpolation quality. High-quality image interpolation may be more
computationally expensive than lower settings.
This section is non-normative.
The output bitmap, when it is not directly displayed by the user agent,
implementations can, instead of updating this bitmap, merely remember the sequence of drawing
operations that have been applied to it until such time as the bitmap's actual data is needed
(for example because of a call to drawImage(), or
the createImageBitmap() factory method). In many
cases, this will be more memory efficient.
The bitmap of a canvas element is the one bitmap that's pretty much always going
to be needed in practice. The output bitmap of a rendering context, when it has one,
is always just an alias to a canvas element's bitmap.
Additional bitmaps are sometimes needed, e.g. to enable fast drawing when the canvas is being painted at a different size than its natural size, or to enable double buffering so that graphics updates, like page scrolling for example, can be processed concurrently while canvas draw commands are being executed.
The output bitmap has an origin-clean flag, which can be set to true or false. Initially, when one of these bitmaps is created, its origin-clean flag must be set to true.
The getContextAttributes() method
steps are to return «[ "alpha" →
this's alpha, "desynchronized" →
this's desynchronized, "colorSpace" → this's
color space, "willReadFrequently" →
this's will read frequently
]».
The restore()
method steps are to pop the top entry in the drawing state stack, and reset the drawing state it
describes. If there is no saved state, then the method must do nothing.
CanvasRenderingContext2D/reset
OffscreenCanvasRenderingContext2D#canvasrenderingcontext2d.reset
CanvasRenderingContext2D/isContextLost
Support in one engine only.
The isContextLost() method steps are to return
this's context lost.
Objects that implement the CanvasPathDrawingStyles interface have attributes and
methods (defined in this section) that control how lines are treated by the object.
When the object implementing the CanvasPathDrawingStyles interface is created, the
lineWidth attribute must initially have the value
1.0.
On getting, it must return the current value. On setting, the current value must be changed to the new value.
When the object implementing the CanvasPathDrawingStyles interface is created, the
lineCap attribute must initially have the value
"butt".
On getting, it must return the current value. On setting, the current value must be changed to the new value.
When the object implementing the CanvasPathDrawingStyles interface is created, the
lineJoin attribute must initially have the value
"miter".
When the object implementing the CanvasPathDrawingStyles interface is created, the
miterLimit attribute must initially have the value
10.0.
When the object implementing the CanvasPathDrawingStyles interface is created, the
lineDashOffset attribute must initially have
the value 0.0.
Font resolution for the font style source object requires a font
source. This is determined for a given object implementing
CanvasTextDrawingStyles by the following steps: [CSSFONTLOAD]
If object's font style source object is a canvas
element, return the element's node document.
Otherwise, object's font style source object is an
OffscreenCanvas object:
Let global be object's relevant global object.
If global is a Window object, then return global's
associated Document.
Assert: global implements
WorkerGlobalScope.
Return global.
Font family names must be interpreted in the context of the font style source
object when the font is to be used; any fonts embedded using @font-face or loaded using FontFace objects that are visible to the
font style source object must therefore be available once they are loaded. (Each font style source
object has a font source, which determines what fonts are available.) If a font
is used before it is fully loaded, or if the font style source object does not have
that font in scope at the time the font is to be used, then it must be treated as if it was an
unknown font, falling back to another as described by the relevant CSS specifications.
[CSSFONTS] [CSSFONTLOAD]
On getting, the font attribute must return the serialized form of the current font of the context (with
no 'line-height' component). [CSSOM]
When the object implementing the CanvasTextDrawingStyles interface is created, the
font of the context must be set to 10px sans-serif. When the 'font-size' component is
set to lengths using percentages, 'em' or 'ex' units, or the 'larger' or
'smaller' keywords, these must be interpreted relative to the computed value of the
'font-size' property of the font style source object at the time that
the attribute is set, if it is an element. When the 'font-weight' component is set to
the relative values 'bolder' and 'lighter', these must be interpreted relative to the
computed value of the 'font-weight' property of the font style
source object at the time that the attribute is set, if it is an element. If the computed values are undefined for a particular case (e.g. because
the font style source object is not an element or is not being
rendered), then the relative keywords must be interpreted relative to the normal-weight
10px sans-serif default.
Objects that implement the CanvasTextDrawingStyles interface have attributes that
control the spacing between letters and words. Such objects have associated letter spacing and word spacing values, which are CSS
<length> values. Initially, both must be the result of parsing "0px" as a CSS
<length>.
CanvasRenderingContext2D/letterSpacing
Support in one engine only.
The letterSpacing setter steps are:
Let parsed be the result of parsing the given value as a CSS <length>.
If parsed is failure, then return.
Set this's letter spacing to parsed.
CanvasRenderingContext2D/wordSpacing
Support in one engine only.
The wordSpacing setter steps are:
Let parsed be the result of parsing the given value as a CSS <length>.
If parsed is failure, then return.
Set this's word spacing to parsed.
CanvasRenderingContext2D/fontKerning
The fontKerning IDL attribute, on
getting, must return the current value. On setting, the current value must be changed to the new
value. When the object implementing the CanvasTextDrawingStyles interface is created,
the fontKerning attribute must
initially have the value "auto".
CanvasRenderingContext2D/fontStretch
Support in one engine only.
The fontStretch IDL attribute, on
getting, must return the current value. On setting, the current value must be changed to the new
value. When the object implementing the CanvasTextDrawingStyles interface is created,
the fontStretch attribute must
initially have the value "normal".
CanvasRenderingContext2D/fontVariantCaps
Support in one engine only.
The fontVariantCaps IDL attribute, on
getting, must return the current value. On setting, the current value must be changed to the new
value. When the object implementing the CanvasTextDrawingStyles interface is created,
the fontVariantCaps attribute must
initially have the value "normal".
CanvasRenderingContext2D/textRendering
Support in one engine only.
The textAlign attribute's allowed keywords are
as follows:
start
Align to the start edge of the text (left side in left-to-right text, right side in right-to-left text).
end
Align to the end edge of the text (right side in left-to-right text, left side in right-to-left text).
left
Align to the left.
right
Align to the right.
center
Align to the center.
The textBaseline
attribute's allowed keywords correspond to alignment points in the
font:

The keywords map to these alignment points as follows:
top
hanging
middle
alphabetic
ideographic
bottom
The direction attribute's allowed keywords are
as follows:
ltr
Treat input to the text preparation algorithm as left-to-right text.
rtl
Treat input to the text preparation algorithm as right-to-left text.
inherit
Default to the directionality of the canvas element or Document
as appropriate.
The fontKerning attribute's allowed keywords
are as follows:
auto
Kerning is applied at the discretion of the user agent.
normal
Kerning is applied.
none
Kerning is not applied.
The fontStretch attribute's allowed keywords
are as follows:
ultra-condensed
Same as CSS 'font-stretch' 'ultra-condensed' setting.
extra-condensed
Same as CSS 'font-stretch' 'extra-condensed' setting.
condensed
Same as CSS 'font-stretch' 'condensed' setting.
semi-condensed
Same as CSS 'font-stretch' 'semi-condensed' setting.
normal
The default setting, where width of the glyphs is at 100%.
semi-expanded
Same as CSS 'font-stretch' 'semi-expanded' setting.
expanded
Same as CSS 'font-stretch' 'expanded' setting.
extra-expanded
Same as CSS 'font-stretch' 'extra-expanded' setting.
ultra-expanded
Same as CSS 'font-stretch' 'ultra-expanded' setting.
The fontVariantCaps attribute's allowed
keywords are as follows:
normal
None of the features listed below are enabled.
small-caps
Same as CSS 'font-variant-caps' 'small-caps' setting.
all-small-caps
Same as CSS 'font-variant-caps' 'all-small-caps' setting.
petite-caps
Same as CSS 'font-variant-caps' 'petite-caps' setting.
all-petite-caps
Same as CSS 'font-variant-caps' 'all-petite-caps' setting.
unicase
Same as CSS 'font-variant-caps' 'unicase' setting.
titling-caps
Same as CSS 'font-variant-caps' 'titling-caps' setting.
The textRendering attribute's allowed
keywords are as follows:
auto
Same as 'auto' in SVG text-rendering property.
optimizeSpeed
Same as 'optimizeSpeed' in SVG text-rendering property.
optimizeLegibility
Same as 'optimizeLegibility' in SVG text-rendering property.
geometricPrecision
Same as 'geometricPrecision' in SVG text-rendering property.
When an object implementing the CanvasPath interface is created, its path must be initialized to zero subpaths.
The following methods allow authors to manipulate the paths
of objects implementing the CanvasPath interface.
For objects implementing the CanvasDrawPath and CanvasTransform
interfaces, the points passed to the methods, and the resulting lines added to current
default path by these methods, must be transformed according to the current transformation matrix before being added to
the path.
The closePath() method, when invoked, must do nothing
if the object's path has no subpaths. Otherwise, it must mark the last subpath as closed, create a
new subpath whose first point is the same as the previous subpath's first point, and finally add
this new subpath to the path.
New points and the lines connecting them are added to subpaths using the methods described below. In all cases, the methods only modify the last subpath in the object's path.
CanvasRenderingContext2D/roundRect
Support in all current engines.
Path2D objectsSupport in all current engines.
Path2D objects can be used to declare paths that are then later used on
objects implementing the CanvasDrawPath interface. In addition to many of the APIs
described in earlier sections, Path2D objects have methods to combine paths, and to
add text to paths.
The current transformation matrix is applied to coordinates when creating the
current default path, and when painting text, shapes, and Path2D
objects, on objects implementing the CanvasTransform interface.
The transformations must be performed in reverse order.
The resetTransform() method, when invoked, must
reset the current transformation matrix to the identity matrix.
Some methods on the CanvasDrawImage and CanvasFillStrokeStyles
interfaces take the union type CanvasImageSource as an argument.
This union type allows objects implementing any of the following interfaces to be used as image sources:
HTMLOrSVGImageElement (img or SVG image
elements)HTMLVideoElement (video elements)HTMLCanvasElement (canvas elements)OffscreenCanvasImageBitmapVideoFrameWhen a CanvasImageSource object represents an HTMLOrSVGImageElement,
the element's image must be used as the source image.
Specifically, when a CanvasImageSource object represents an animated image in an
HTMLOrSVGImageElement, the user agent must use the default image of the animation
(the one that the format defines is to be used when animation is not supported or is disabled),
or, if there is no such image, the first frame of the animation, when rendering the image for
CanvasRenderingContext2D APIs.
When a CanvasImageSource object represents an HTMLVideoElement, then
the frame at the current playback position when the method with the argument is
invoked must be used as the source image when rendering the image for
CanvasRenderingContext2D APIs, and the source image's dimensions must be the natural width and natural height of the media resource
(i.e., after any aspect-ratio correction has been applied).
When a CanvasImageSource object represents an HTMLCanvasElement, the
element's bitmap must be used as the source image.
When a CanvasImageSource object represents an element that is being
rendered and that element has been resized, the original image data of the source image
must be used, not the image as it is rendered (e.g. width and
height attributes on the source element have no effect on how
the object is interpreted when rendering the image for CanvasRenderingContext2D
APIs).
When a CanvasImageSource object represents an ImageBitmap, the
object's bitmap image data must be used as the source image.
When a CanvasImageSource object represents an OffscreenCanvas, the
object's bitmap must be used as the source image.
When a CanvasImageSource object represents a VideoFrame, the object's
pixel data must be used as the source image, and the source image's dimensions must be the
object's [[display width]] and [[display height]].
Objects that implement the CanvasFillStrokeStyles interface have attributes and
methods (defined in this section) that control how shapes are treated by the object.
When the value is a CSS color, it must not be affected by the transformation matrix when used to draw on bitmaps.
The fillStyle setter steps are:
If the given value is a string, then:
Let context be this's canvas attribute's value, if that is an element;
otherwise null.
Let parsedValue be the result of parsing the given value with context if non-null.
If parsedValue is failure, then return.
Set this's fill style to parsedValue.
Return.
If the given value is a CanvasPattern object that is marked as not origin-clean, then set
this's origin-clean flag to
false.
Set this's fill style to the given value.
The strokeStyle setter steps are:
If the given value is a string, then:
Let context be this's canvas attribute's value, if that is an element;
otherwise null.
Let parsedValue be the result of parsing the given value with context if non-null.
If parsedValue is failure, then return.
Set this's stroke style to parsedValue.
Return.
If the given value is a CanvasPattern object that is marked as not origin-clean, then set
this's origin-clean flag to
false.
Set this's stroke style to the given value.
There are three types of gradients, linear gradients, radial gradients, and conic gradients,
represented by objects implementing the opaque CanvasGradient interface.
Once a gradient has been created (see below), stops are placed along it to define how the colors are distributed along the gradient. The color of the gradient at each stop is the color specified for that stop. Between each such stop, the colors and the alpha component must be linearly interpolated over the RGBA space without premultiplying the alpha value to find the color to use at that offset. Before the first stop, the color must be the color of the first stop. After the last stop, the color must be the color of the last stop. When there are no stops, the gradient is transparent black.
Linear gradients must be rendered such that all points on a line perpendicular to the line that crosses the start and end points have the color at the point where those two lines cross (with the colors coming from the interpolation and extrapolation described above). The points in the linear gradient must be transformed as described by the current transformation matrix when rendering.
If x0 = x1 and y0 = y1, then the linear gradient must paint nothing.
Radial gradients must be rendered by following these steps:
If x0 = x1 and y0 = y1 and r0 = r1, then the radial gradient must paint nothing. Return.
Let x(ω) = (x1-x0)ω + x0
Let y(ω) = (y1-y0)ω + y0
Let r(ω) = (r1-r0)ω + r0
Let the color at ω be the color at that position on the gradient (with the colors coming from the interpolation and extrapolation described above).
For all values of ω where r(ω) > 0, starting with the value of ω nearest to positive infinity and ending with the value of ω nearest to negative infinity, draw the circumference of the circle with radius r(ω) at position (x(ω), y(ω)), with the color at ω, but only painting on the parts of the bitmap that have not yet been painted on by earlier circles in this step for this rendering of the gradient.
The resulting radial gradient must then be transformed as described by the current transformation matrix when rendering.
It follows the same rendering rule as CSS 'conic-gradient' and it is equivalent to CSS 'conic-gradient(from adjustedStartAnglerad at xpx ypx, angularColorStopList)'. Here:
adjustedStartAngle is given by startAngle + π/2;
angularColorStopList is given by the color stops that have been added to the
CanvasGradient using addColorStop(), with the color stop offsets
interpreted as percentages.
Gradients must be painted only where the relevant stroking or filling effects requires that they be drawn.
Patterns are represented by objects implementing the opaque CanvasPattern
interface.
Modifying the image used when creating a CanvasPattern object
after calling the createPattern() method must
not affect the pattern(s) rendered by the CanvasPattern object.
Patterns have a transformation matrix, which controls how the pattern is used when it is painted. Initially, a pattern's transformation matrix must be the identity matrix.
When a pattern is to be rendered within an area, the user agent must run the following steps to determine what is rendered:
Create an infinite transparent black bitmap.
Place a copy of the image on the bitmap, anchored such that its top left corner is at the
origin of the coordinate space, with one coordinate space unit per CSS
pixel of the image, then place repeated copies of this image horizontally to the left and
right, if the repetition behavior is "repeat-x", or vertically up and
down, if the repetition behavior is "repeat-y", or in all four
directions all over the bitmap, if the repetition behavior is "repeat".
If the original image data is a bitmap image, then the value painted at a point in the area
of the repetitions is computed by filtering the original image data. When scaling up, if the
imageSmoothingEnabled attribute is
set to false, then the image must be rendered using nearest-neighbor interpolation. Otherwise,
the user agent may use any filtering algorithm (for example bilinear interpolation or
nearest-neighbor). User agents which support multiple filtering algorithms may use the value of
the imageSmoothingQuality attribute
to guide the choice of filtering algorithm. When such a filtering algorithm requires a pixel
value from outside the original image data, it must instead use the value from wrapping the
pixel's coordinates to the original image's dimensions. (That is, the filter uses 'repeat'
behavior, regardless of the value of the pattern's repetition behavior.)
Transform the resulting bitmap according to the pattern's transformation matrix.
Transform the resulting bitmap again, this time according to the current transformation matrix.
Replace any part of the image outside the area in which the pattern is to be rendered with transparent black.
The resulting bitmap is what is to be rendered, with the same origin and same scale.
If a radial gradient or repeated pattern is used when the transformation matrix is singular, then the resulting style must be transparent black (otherwise the gradient or pattern would be collapsed to a point or line, leaving the other pixels undefined). Linear gradients and solid colors always define all points even with singular transformation matrices.
Objects that implement the CanvasRect interface provide the following methods for
immediately drawing rectangles to the bitmap. The methods each take four arguments; the first two
give the x and y coordinates of the top left of the rectangle, and the
second two give the width w and height h of the rectangle, respectively.
The current transformation matrix must be applied to the following four coordinates, which form the path that must then be closed to get the specified rectangle: (x, y), (x+w, y), (x+w, y+h), (x, y+h).
Shapes are painted without affecting the current default path, and are subject to
the clipping region, and, with the exception of clearRect(), also shadow
effects, global alpha, and the
current compositing and blending operator.
If both w and h are zero, the path has a single subpath with just one point (x, y), and no lines, and this method thus has no effect (the trace a path algorithm returns an empty path in that case).
If just one of either w or h is zero, then the path has a single subpath consisting of two points, with coordinates (x, y) and (x+w, y+h), in that order, connected by a single straight line.
Otherwise, the path has a single subpath consisting of four points, with coordinates (x, y), (x+w, y), (x+w, y+h), and (x, y+h), connected to each other in that order by straight lines.
Support in all current engines.
Objects that implement the CanvasText interface provide the following methods for
rendering text.
When the intended path is a Path2D object, the coordinates and lines
of its subpaths must be transformed according to the current transformation matrix on the object
implementing the CanvasTransform interface when used by these methods (without
affecting the Path2D object itself). When the intended path is the current
default path, it is not affected by the transform. (This is because transformations
already affect the current default path when it is constructed, so applying it when
it is painted as well would result in a double transformation.)
Paths, when filled or stroked, must be painted without affecting the current default
path or any Path2D objects, and must be subject to shadow effects, global
alpha, the clipping region, and the current compositing and blending
operator. (The effect of transformations is described above and varies based on which path
is being used.)
The clip steps, given a CanvasDrawPath context, a
Path2D-or-null path, and a fill rule fillRule,
are to create a new clipping region by calculating the intersection of
context's current clipping region and the area described by the intended
path for path, using the fill rule indicated by
fillRule. Open subpaths must be implicitly closed when computing the clipping region,
without affecting the actual subpaths. The new clipping region replaces the current clipping
region.
When the context is initialized, its current clipping region must be set to the largest infinite surface (i.e. by default, no clipping occurs).
Objects that implement the CanvasUserInterface interface provide the following
methods to draw focus rings.
User agents should not implicitly close open subpaths in the intended path when drawing the focus ring.
"Inform the user", as used in this section, does not imply any persistent state change. It could mean, for instance, calling a system accessibility API to notify assistive technologies such as magnification tools so that the user's magnifier moves to the given area of the canvas. However, it does not associate the path with the element, or provide a region for tactile feedback, etc.
This method can be invoked with three different sets of arguments:
drawImage(image, dx, dy)
drawImage(image, dx, dy, dw, dh)
drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh)
When the drawImage() method is invoked, the user
agent must run these steps:
If any of the arguments are infinite or NaN, then return.
Let usability be the result of checking the usability of image.
If usability is bad, then return (without drawing anything).
Establish the source and destination rectangles as follows:
If not specified, the dw and dh arguments must default to the values of sw and sh, interpreted such that one CSS pixel in the image is treated as one unit in the output bitmap's coordinate space. If the sx, sy, sw, and sh arguments are omitted, then they must default to 0, 0, the image's natural width in image pixels, and the image's natural height in image pixels, respectively. If the image has no natural dimensions, then the concrete object size must be used instead, as determined using the CSS "Concrete Object Size Resolution" algorithm, with the specified size having neither a definite width nor height, nor any additional constraints, the object's natural properties being those of the image argument, and the default object size being the size of the output bitmap. [CSSIMAGES]
The source rectangle is the rectangle whose corners are the four points (sx, sy), (sx+sw, sy), (sx+sw, sy+sh), (sx, sy+sh).
The destination rectangle is the rectangle whose corners are the four points (dx, dy), (dx+dw, dy), (dx+dw, dy+dh), (dx, dy+dh).
When the source rectangle is outside the source image, the source rectangle must be clipped to the source image and the destination rectangle must be clipped in the same proportion.
If one of the sw or sh arguments is zero, then return. Nothing is painted.
Paint the region of the image argument specified by the source rectangle on the region of the rendering context's output bitmap specified by the destination rectangle, after applying the current transformation matrix to the destination rectangle.
The image data must be processed in the original direction, even if the dimensions given are negative.
When scaling up, if the imageSmoothingEnabled attribute is set to
true, the user agent should attempt to apply a smoothing algorithm to the image data when it is
scaled. User agents which support multiple filtering algorithms may use the value of the imageSmoothingQuality attribute to guide
the choice of filtering algorithm when the imageSmoothingEnabled attribute is set to
true. Otherwise, the image must be rendered using nearest-neighbor interpolation.
If the original image data is a bitmap image, then the value painted at a point in the destination rectangle is computed by filtering the original image data. The user agent may use any filtering algorithm (for example bilinear interpolation or nearest-neighbor). When the filtering algorithm requires a pixel value from outside the original image data, it must instead use the value from the nearest edge pixel. (That is, the filter uses 'clamp-to-edge' behavior.) When the filtering algorithm requires a pixel value from outside the source rectangle but inside the original image data, then the value from the original image data must be used.
Images are painted without affecting the current path, and are subject to shadow effects, global alpha, the clipping region, and the current compositing and blending operator.
If image is not origin-clean, then set the
CanvasRenderingContext2D's origin-clean flag to false.
Objects that implement the CanvasImageData interface provide the following methods
for reading and writing pixel data to the bitmap.
To initialize an ImageData object imageData, given a
positive integer number of rows rows, a positive integer number of pixels per row
pixelsPerRow, an optional ImageDataSettings settings, an optional Uint8ClampedArray source, and an optional
PredefinedColorSpace defaultColorSpace:
Otherwise (source was not given), initialize the data attribute of imageData to a new Uint8ClampedArray object. The Uint8ClampedArray object must use a new Canvas
Pixel ArrayBuffer for its storage, and must have a
zero start offset and a length equal to the length of its storage, in bytes. The Canvas
Pixel ArrayBuffer must have the correct size to
store rows × pixelsPerRow pixels.
If the Canvas Pixel ArrayBuffer cannot be
allocated, then rethrow the RangeError thrown by JavaScript,
and return.
If settings was given and settings["colorSpace"] exists, then initialize the colorSpace attribute of imageData to
settings["colorSpace"].
Otherwise, if defaultColorSpace was given, then initialize the colorSpace attribute of imageData to
defaultColorSpace.
Otherwise, initialize the colorSpace
attribute of imageData to "srgb".
ImageData objects are serializable objects. Their serialization
steps, given value and serialized, are:
Set serialized.[[Data]] to the sub-serialization of the value of
value's data attribute.
Set serialized.[[Width]] to the value of value's width attribute.
Set serialized.[[Height]] to the value of value's height attribute.
Set serialized.[[ColorSpace]] to the value of value's colorSpace attribute.
Their deserialization steps, given serialized, value, and targetRealm, are:
Initialize value's data attribute
to the sub-deserialization of serialized.[[Data]].
Initialize value's width attribute
to serialized.[[Width]].
Initialize value's height attribute
to serialized.[[Height]].
Initialize value's colorSpace
attribute to serialized.[[ColorSpace]].
When the last four arguments to this method are omitted, they must be assumed to have the
values 0, 0, the width member of the imagedata structure, and the height
member of the imagedata structure, respectively.
The method, when invoked, must act as follows:
Let buffer be imagedata's data attribute value's [[ViewedArrayBuffer]] internal
slot.
If IsDetachedBuffer(buffer) is true, then throw an
"InvalidStateError" DOMException.
If dirtyWidth is negative, then let dirtyX be dirtyX+dirtyWidth, and let dirtyWidth be equal to the absolute magnitude of dirtyWidth.
If dirtyHeight is negative, then let dirtyY be dirtyY+dirtyHeight, and let dirtyHeight be equal to the absolute magnitude of dirtyHeight.
If dirtyX is negative, then let dirtyWidth be dirtyWidth+dirtyX, and let dirtyX be zero.
If dirtyY is negative, then let dirtyHeight be dirtyHeight+dirtyY, and let dirtyY be zero.
If dirtyX+dirtyWidth is greater than the width attribute of the imagedata argument, then
let dirtyWidth be the value of that width
attribute, minus the value of dirtyX.
If dirtyY+dirtyHeight is greater than the height attribute of the imagedata argument, then
let dirtyHeight be the value of that height attribute, minus the value of dirtyY.
If, after those changes, either dirtyWidth or dirtyHeight are negative or zero, then return without affecting any bitmaps.
For all integer values of x and y where dirtyX ≤ x < dirtyX+dirtyWidth and dirtyY ≤ y < dirtyY+dirtyHeight, copy the
four channels of the pixel with coordinate (x, y) in
the imagedata data structure's Canvas Pixel
ArrayBuffer to the pixel with coordinate (dx+x, dy+y)
in the rendering context's output bitmap.
The current path, transformation matrix, shadow attributes, global alpha, the clipping region, and current compositing and blending operator must not affect the methods described in this section.
Objects that implement the CanvasCompositing interface have a global alpha value and a current compositing
and blending operator value that both affect all the drawing operations on this
object.
The globalAlpha setter steps are:
If the given value is either infinite, NaN, or not in the range 0.0 to 1.0, then return.
Otherwise, set this's global alpha to the given value.
The globalCompositeOperation setter steps
are:
If the given value is not identical to any of the values that the <blend-mode> or the <composite-mode> properties are defined to take, then return. [COMPOSITE]
Otherwise, set this's current compositing and blending operator to the given value.
Objects that implement the CanvasImageSmoothing interface have attributes that
control how image smoothing is performed.
The imageSmoothingQuality attribute, on
getting, must return the last value it was set to. On setting, it must be set to the new value.
When the object implementing the CanvasImageSmoothing interface is created, the
attribute must be set to "low".
All drawing operations on an object which implements the CanvasShadowStyles
interface are affected by the four global shadow attributes.
The shadowColor setter steps are:
Let context be this's canvas attribute's value, if that is an element; otherwise
null.
Let parsedValue be the result of parsing the given value with context if non-null.
If parsedValue is failure, then return.
Set this's shadow color to parsedValue.
When the context is created, the shadow offset attributes must initially have the value 0.
On getting, they must return their current value. On setting, the attribute being set must be set to the new value, except if the value is infinite or NaN, in which case the new value must be ignored.
When the context is created, the shadowBlur
attribute must initially have the value 0.
On getting, the attribute must return its current value. On setting, the attribute must be set to the new value, except if the value is negative, infinite or NaN, in which case the new value must be ignored.
When shadows are drawn, they must be rendered as follows:
Let A be an infinite transparent black bitmap on which the source image for which a shadow is being created has been rendered.
Let B be an infinite transparent black bitmap, with a coordinate space and an origin identical to A.
Copy the alpha channel of A to B, offset by shadowOffsetX in the positive x
direction, and shadowOffsetY in the positive
y direction.
If shadowBlur is greater than 0:
Let σ be half the value of shadowBlur.
Perform a 2D Gaussian Blur on B, using σ as the standard deviation.
User agents may limit values of σ to an implementation-specific maximum value to avoid exceeding hardware limitations during the Gaussian blur operation.
Set the red, green, and blue components of every pixel in B to the red, green, and blue components (respectively) of the shadow color.
Multiply the alpha component of every pixel in B by the alpha component of the shadow color.
The shadow is in the bitmap B, and is rendered as part of the drawing model described below.
If the current compositing and blending operator is "copy", then shadows effectively won't render (since the shape will
overwrite the shadow).
The filter getter steps are to return
this's current filter.
The filter setter steps are:
If the given value is "none", then set this's current filter to "none"
and return.
Let parsedValue be the result of parsing the given values as a <filter-value-list>. If any property-independent style sheet syntax like 'inherit' or 'initial' is present, then this parsing must return failure.
If parsedValue is failure, then return.
Set this's current filter to the given value.
Coordinates used in the value of the current filter are interpreted such that one pixel is equivalent to one SVG user space unit and to one canvas coordinate space unit. Filter coordinates are not affected by the current transformation matrix. The current transformation matrix affects only the input to the filter. Filters are applied in the output bitmap's coordinate space.
When the value of the current filter is a
string parsable as a <filter-value-list> which defines lengths using
percentages or using 'em' or 'ex' units, these must be interpreted
relative to the computed value of the 'font-size' property of the
font style source object at the time that the attribute is set. If the computed values are undefined for a particular case (e.g. because
the font style source object is not an element or is not being
rendered), then the relative keywords must be interpreted relative to the default value of
the font attribute. The 'larger' and 'smaller' keywords
are not supported.
If the value of the current filter is a string parseable as a <filter-value-list> with a reference to an SVG filter in the same document, and this SVG filter changes, then the changed filter is used for the next draw operation.
If the value of the current filter is a string parseable as a <filter-value-list> with a reference to an SVG filter in an external resource document and that document is not loaded when a drawing operation is invoked, then the drawing operation must proceed with no filtering.
This section is non-normative.
Since drawing is performed using filter value "none" until an
externally-defined filter has finished loading, authors might wish to determine whether such a
filter has finished loading before proceeding with a drawing operation. One way to accomplish
this is to load the externally-defined filter elsewhere within the same page in some element that
sends a load event (for example, an SVG use
element), and wait for the load event to be dispatched.
When a shape or image is painted, user agents must follow these steps, in the order given (or act as if they do):
Render the shape or image onto an infinite transparent black bitmap, creating image A, as described in the previous sections. For shapes, the current fill, stroke, and line styles must be honored, and the stroke must itself also be subjected to the current transformation matrix.
Multiply the alpha component of every pixel in A by global alpha.
When the current filter is set to a
value other than "none" and all the externally-defined filters it
references, if any, are in documents that are currently loaded, then use image A as
the input to the current filter, creating
image B. If the current filter
is a string parseable as a <filter-value-list>, then draw using the current filter in the same manner as SVG.
Otherwise, let B be an alias for A.
When shadows are drawn, render the shadow from image B, using the current shadow styles, creating image C.
When shadows are drawn, composite C within the clipping region over the current output bitmap using the current compositing and blending operator.
Composite B within the clipping region over the current output bitmap using the current compositing and blending operator.
When compositing onto the output bitmap, pixels that would fall outside of the output bitmap must be discarded.
When a canvas is interactive, authors should include focusable elements in the element's fallback content corresponding to each focusable part of the canvas, as in the example above.
When rendering focus rings, to ensure that focus rings have the appearance of native focus
rings, authors should use the drawFocusIfNeeded() method, passing it the
element for which a ring is being drawn. This method only draws the focus ring if the element is
focused, so that it can simply be called whenever drawing the element, without
checking whether the element is focused or not first.
Authors should avoid implementing text editing controls
using the canvas element. Doing so has a large number of disadvantages:
This is a huge amount of work, and authors are most strongly encouraged to avoid doing any of
it by instead using the input element, the textarea element, or the
contenteditable attribute.
This section is non-normative.
ImageBitmap rendering contextImageBitmapRenderingContext is a performance-oriented interface that provides a
low overhead method for displaying the contents of ImageBitmap objects. It uses
transfer semantics to reduce overall memory consumption. It also streamlines performance by
avoiding intermediate compositing, unlike the drawImage() method of
CanvasRenderingContext2D.
Using an img element as an intermediate for getting an image resource into a
canvas, for example, would result in two copies of the decoded image existing in memory at the
same time: the img element's copy, and the one in the canvas's backing store. This
memory cost can be prohibitive when dealing with extremely large images. This can be avoided by
using ImageBitmapRenderingContext.
ImageBitmapRenderingContext interfaceSupport in all current engines.
An ImageBitmapRenderingContext object also has an alpha flag, which can be set to true or
false. When an ImageBitmapRenderingContext object has its alpha flag set to false, the contents
of the canvas element to which the context is bound are obtained by
compositing the context's output bitmap onto an
opaque black bitmap of the same size using the source-over compositing operator. If the alpha flag is set to true, then the
output bitmap is used as
the contents of the canvas element to which the context is bound.
[COMPOSITE]
OffscreenCanvas interfaceSupport in all current engines.
OffscreenCanvas objects are used to create rendering contexts, much like an
HTMLCanvasElement, but with no connection to the DOM. This makes it possible to
use canvas rendering contexts in workers.
An OffscreenCanvas object can have a rendering context bound to it. Initially,
it does not have a bound rendering context. To keep track of whether it has a rendering context
or not, and what kind of rendering context it is, an OffscreenCanvas object also
has a context mode, which is initially none but can be changed to either 2d, bitmaprenderer, webgl, webgl2, webgpu, or detached by algorithms defined in this
specification.
The constructor OffscreenCanvas(width,
height), when invoked, must create a new OffscreenCanvas
object with its bitmap initialized to a rectangular
array of transparent black pixels of the dimensions specified by width and
height; and its width and height attributes initialized to width and
height respectively.
OffscreenCanvas objects are transferable. Their transfer steps, given value and
dataHolder, are as follows:
If value's context mode is
not equal to none, then throw an
"InvalidStateError" DOMException.
Set value's context mode to detached.
Let width and height be the dimensions of value's bitmap.
Unset value's bitmap.
Set dataHolder.[[Width]] to width and dataHolder.[[Height]] to height.
Set dataHolder.[[PlaceholderCanvas]] to be a weak reference to
value's placeholder canvas
element, if value has one, or null if it does not.
Their transfer-receiving steps, given dataHolder and value, are:
Initialize value's bitmap to a rectangular array of transparent black pixels with width given by dataHolder.[[Width]] and height given by dataHolder.[[Height]].
If dataHolder.[[PlaceholderCanvas]] is not null, set value's placeholder canvas element to
dataHolder.[[PlaceholderCanvas]] (while maintaining the weak reference
semantics).
If either the width or height attributes of
an OffscreenCanvas object are set (to a new value or to the same value as before) and
the OffscreenCanvas object's context
mode is 2d, then reset the rendering
context to its default state and resize the OffscreenCanvas object's bitmap to the new values of the width and height attributes.
The resizing behavior for "webgl" and "webgl2" contexts is defined in the WebGL
specifications. [WEBGL]
The resizing behavior for "webgpu" context
is defined in WebGPU. [WEBGPU]
The following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the
OffscreenCanvas interface:
| Event handler | Event handler event type |
|---|---|
oncontextlost | contextlost
|
oncontextrestored | contextrestored
|
OffscreenCanvasRenderingContext2D
Support in all current engines.
The OffscreenCanvasRenderingContext2D object is a rendering context for drawing to
the bitmap of an OffscreenCanvas object.
It is similar to the CanvasRenderingContext2D object, with the following
differences:
there is no support for user interface features;
its canvas attribute refers to an
OffscreenCanvas object rather than a canvas element;
The canvas attribute, on getting, must return this
OffscreenCanvasRenderingContext2D's associated OffscreenCanvas
object.
The canvas APIs provide mechanisms for specifying the color space of the canvas's
backing store. The default backing store color space for all canvas APIs is
'srgb'.
Color space conversion must be applied to the canvas's
backing store when rendering the canvas to the output device. This color space conversion must be
identical to the color space conversion that would be applied to an img element with
a color profile that specifies the same color
space as the canvas's backing store.
When drawing content to a 2D context, all inputs must be converted to the context's color space before drawing. Interpolation of gradient color stops must be performed on color values after conversion to the context's color space. Alpha blending must be performed on values after conversion to the context's color space.
The image file's pixel data must be the bitmap's pixel data scaled to one image pixel per coordinate space unit, and if the file format used supports encoding resolution metadata, the resolution must be given as 96dpi (one image pixel per CSS pixel).
If type is supplied, then it must be interpreted as a MIME type giving the format to use. If the type has any parameters, then it must be treated as not supported.
User agents must support PNG ("image/png"). User agents may support other types.
If the user agent does not support the requested type, then it must create the file using the PNG
format. [PNG]
User agents must convert the provided type to ASCII lowercase before establishing if they support that type.
For image types that do not support an alpha channel, the serialized image must be the bitmap image composited onto an opaque black background using the source-over compositing operator.
For image types that support color profiles, the serialized image must include a color profile indicating the color space of the underlying bitmap. For image types that do not support color profiles, the serialized image must be converted to the 'srgb' color space using 'relative-colorimetric' rendering intent.
If type is an image format that supports variable quality (such as
"image/jpeg"), quality is given, and type is not
"image/png", then, if quality is a Number
in the range 0.0 to 1.0 inclusive, the user agent must treat quality as the desired
quality level. Otherwise, the user agent must use its default quality value, as if the
quality argument had not been given.
canvas elementsThis section is non-normative.
Information leakage can occur if scripts from one origin can access information (e.g. read pixels) from images from another origin (one that isn't the same).
To mitigate this, bitmaps used with canvas elements, OffscreenCanvas
objects, and ImageBitmap objects are defined to have a flag indicating whether they
are origin-clean. All bitmaps start with their
origin-clean set to true. The flag is set to
false when cross-origin images are used.
The toDataURL(), toBlob(), and getImageData() methods check the flag and will
throw a "SecurityError" DOMException rather than leak
cross-origin data.
The value of the origin-clean flag is
propagated from a source's bitmap to a new ImageBitmap object by createImageBitmap(). Conversely, a destination canvas element's bitmap will have its origin-clean flags set to false by drawImage if the source image is an
ImageBitmap object whose bitmap has its origin-clean flag set to false.
The flag can be reset in certain situations; for example, when changing the value of the
width or the height content attribute of the canvas element
to which a CanvasRenderingContext2D is bound, the bitmap is
cleared and its origin-clean flag is reset.
When using an ImageBitmapRenderingContext, the value of the origin-clean flag is propagated from
ImageBitmap objects when they are transferred to the canvas
via transferFromImageBitmap().
Under non-premultiplied alpha, the red, green, and blue channels of a pixel represent that pixel's color, and its alpha channel represents that pixel's opacity.
Under premultiplied alpha, however, the red, green, and blue channels of a pixel represent the amounts of color that the pixel adds to the image, and its alpha channel represents the amount that the pixel obscures whatever is behind it.
As certain colors can only be represented under premultiplied alpha (for instance, additive colors), and others can only be represented under non-premultiplied alpha (for instance, "invisible" colors which hold certain red, green, and blue values even with no opacity); and division and multiplication on 8-bit integers (which is how canvas's colors are currently stored) entails a loss of precision, converting between premultiplied and non-premultiplied alpha is a lossy operation on colors that are not fully opaque.
A CanvasRenderingContext2D's output bitmap and an
OffscreenCanvasRenderingContext2D's output bitmap must use premultiplied
alpha to represent transparent colors.
Support in all current engines.
This section is non-normative.
Custom elements provide a way for authors to build their own fully-featured DOM elements. Although authors could always use non-standard elements in their documents, with application-specific behavior added after the fact by scripting or similar, such elements have historically been non-conforming and not very functional. By defining a custom element, authors can inform the parser how to properly construct an element and how elements of that class should react to changes.
Custom elements are part of a larger effort to "rationalise the platform", by explaining existing platform features (like the elements of HTML) in terms of lower-level author-exposed extensibility points (like custom element definition). Although today there are many limitations on the capabilities of custom elements—both functionally and semantically—that prevent them from fully explaining the behaviors of HTML's existing elements, we hope to shrink this gap over time.
This section is non-normative.
For the purposes of illustrating how to create an autonomous custom element, let's define a custom element that encapsulates rendering a small icon for a country flag. Our goal is to be able to use it like so:
To do this, we first declare a class for the custom element, extending
HTMLElement:
class FlagIcon extends HTMLElement {
constructor() {
super ();
this . _countryCode = null ;
}
static observedAttributes = [ "country" ];
attributeChangedCallback( name, oldValue, newValue) {
// name will always be "country" due to observedAttributes
this . _countryCode = newValue;
this . _updateRendering();
}
connectedCallback() {
this . _updateRendering();
}
get country() {
return this . _countryCode;
}
set country( v) {
this . setAttribute( "country" , v);
}
_updateRendering() {
// Left as an exercise for the reader. But, you'll probably want to
// check this.ownerDocument.defaultView to see if we've been
// inserted into a document with a browsing context, and avoid
// doing any work if not.
}
}
We then need to use this class to define the element:
customElements. define( "flag-icon" , FlagIcon);
At this point, our above code will work! The parser, whenever it sees the flag-icon tag, will construct a new instance of our FlagIcon class, and tell our code about its new country
attribute, which we then use to set the element's internal state and update its rendering (when
appropriate).
You can also create flag-icon elements using the DOM API:
const flagIcon = document. createElement( "flag-icon" )
flagIcon. country = "jp"
document. body. appendChild( flagIcon)
Finally, we can also use the custom element constructor itself. That is, the above code is equivalent to:
const flagIcon = new FlagIcon()
flagIcon. country = "jp"
document. body. appendChild( flagIcon)
This section is non-normative.
Adding a static formAssociated property, with a true value, makes an
autonomous custom element a form-associated custom element. The
ElementInternals interface helps you to implement functions and properties common
to form control elements.
class MyCheckbox extends HTMLElement {
static formAssociated = true ;
static observedAttributes = [ 'checked' ];
constructor() {
super ();
this . _internals = this . attachInternals();
this . addEventListener( 'click' , this . _onClick. bind( this ));
}
get form() { return this . _internals. form; }
get name() { return this . getAttribute( 'name' ); }
get type() { return this . localName; }
get checked() { return this . hasAttribute( 'checked' ); }
set checked( flag) { this . toggleAttribute( 'checked' , Boolean( flag)); }
attributeChangedCallback( name, oldValue, newValue) {
// name will always be "checked" due to observedAttributes
this . _internals. setFormValue( this . checked ? 'on' : null );
}
_onClick( event) {
this . checked = ! this . checked;
}
}
customElements. define( 'my-checkbox' , MyCheckbox);
You can use the custom element my-checkbox like a built-in
form-associated element. For example, putting it in form or label
associates the my-checkbox element with them, and submitting the
form will send data provided by my-checkbox implementation.
This section is non-normative.
By using the appropriate properties of ElementInternals, your custom element can
have default accessibility semantics. The following code expands our form-associated checkbox from
the previous section to properly set its default role and checkedness, as viewed by accessibility
technology:
class MyCheckbox extends HTMLElement {
static formAssociated = true ;
static observedAttributes = [ 'checked' ];
constructor() {
super ();
this . _internals = this . attachInternals();
this . addEventListener( 'click' , this . _onClick. bind( this ));
this . _internals. role = 'checkbox' ;
this . _internals. ariaChecked = 'false' ;
}
get form() { return this . _internals. form; }
get name() { return this . getAttribute( 'name' ); }
get type() { return this . localName; }
get checked() { return this . hasAttribute( 'checked' ); }
set checked( flag) { this . toggleAttribute( 'checked' , Boolean( flag)); }
attributeChangedCallback( name, oldValue, newValue) {
// name will always be "checked" due to observedAttributes
this . _internals. setFormValue( this . checked ? 'on' : null );
this . _internals. ariaChecked = this . checked;
}
_onClick( event) {
this . checked = ! this . checked;
}
}
customElements. define( 'my-checkbox' , MyCheckbox);
Note that, like for built-in elements, these are only defaults, and can be overridden by the
page author using the role and aria-* attributes:
Custom element authors are encouraged to state what aspects of their accessibility semantics
are strong native semantics, i.e., should not be overridden by users of the custom element. In our
example, the author of the my-checkbox element would state that its
role and aria-checked values are strong
native semantics, thus discouraging code such as the above.
This section is non-normative.
Customized built-in elements are a distinct kind of custom element, which are defined slightly differently and used very differently compared to autonomous custom elements. They exist to allow reuse of behaviors from the existing elements of HTML, by extending those elements with new custom functionality. This is important since many of the existing behaviors of HTML elements can unfortunately not be duplicated by using purely autonomous custom elements. Instead, customized built-in elements allow the installation of custom construction behavior, lifecycle hooks, and prototype chain onto existing elements, essentially "mixing in" these capabilities on top of the already-existing element.
Customized built-in elements require a distinct syntax from autonomous custom elements because user agents and other software key off an element's local name in order to identify the element's semantics and behavior. That is, the concept of customized built-in elements building on top of existing behavior depends crucially on the extended elements retaining their original local name.
In this example, we'll be creating a customized built-in element named plastic-button, which behaves like a normal button but gets fancy animation
effects added whenever you click on it. We start by defining a class, just like before, although
this time we extend HTMLButtonElement instead of HTMLElement:
class PlasticButton extends HTMLButtonElement {
constructor() {
super ();
this . addEventListener( "click" , () => {
// Draw some fancy animation effects!
});
}
}
When defining our custom element, we have to also specify the extends option:
customElements. define( "plastic-button" , PlasticButton, { extends : "button" });
In general, the name of the element being extended cannot be determined simply by looking at
what element interface it extends, as many elements share the same interface (such as
q and blockquote both sharing HTMLQuoteElement).
To construct our customized built-in element from parsed HTML source text, we use
the is attribute on a button element:
Trying to use a customized built-in element as an autonomous custom
element will not work; that is, <plastic-button>Click
me?</plastic-button> will simply create an HTMLElement with no special
behavior.
If you need to create a customized built-in element programmatically, you can use the following
form of createElement():
const plasticButton = document. createElement( "button" , { is: "plastic-button" });
plasticButton. textContent = "Click me!" ;
And as before, the constructor will also work:
const plasticButton2 = new PlasticButton();
console. log( plasticButton2. localName); // will output "button"
console. assert( plasticButton2 instanceof PlasticButton);
console. assert( plasticButton2 instanceof HTMLButtonElement);
Note that when creating a customized built-in element programmatically, the is attribute will not be present in the DOM, since it was not explicitly
set. However, it will be added to the output when
serializing:
console. assert( ! plasticButton. hasAttribute( "is" ));
console. log( plasticButton. outerHTML); // will output '<button is="plastic-button"></button>'
Regardless of how it is created, all of the ways in which button is special
apply to such "plastic buttons" as well: their focus behavior, ability to participate in form submission, the disabled attribute, and so on.
Customized built-in elements are designed to allow extension of existing HTML
elements that have useful user-agent supplied behavior or APIs. As such, they can only extend
existing HTML elements defined in this specification, and cannot extend legacy elements such as
bgsound, blink, isindex, keygen,
multicol, nextid, or spacer that have been defined to use
HTMLUnknownElement as their element interface.
One reason for this requirement is future-compatibility: if a customized built-in
element was defined that extended a currently-unknown element, for example combobox, this would prevent this specification from defining a combobox element in the future, as consumers of the derived customized
built-in element would have come to depend on their base element having no interesting
user-agent-supplied behavior.
This section is non-normative.
As specified below, and alluded to above, simply defining and using an element called
taco-button does not mean that such elements represent buttons. That is, tools such as web browsers, search engines,
or accessibility technology will not automatically treat the resulting element as a button just
based on its defined name.
To convey the desired button semantics to a variety of users, while still using an autonomous custom element, a number of techniques would need to be employed:
The addition of the tabindex attribute would make the
taco-button focusable. Note that if the
taco-button were to become logically disabled, the tabindex attribute would need to be removed.
The addition of an ARIA role and various ARIA states and properties helps convey semantics
to accessibility technology. For example, setting the role to "button" will convey the semantics that this is a button,
enabling users to successfully interact with the control using usual button-like interactions in
their accessibility technology. Setting the aria-label
property is necessary to give the button an accessible
name, instead of having accessibility technology traverse its child text nodes and
announce them. And setting the aria-disabled state to
"true" when the button is logically disabled conveys to accessibility
technology the button's disabled state.
The addition of event handlers to handle commonly-expected button behaviors helps convey
the semantics of the button to web browser users. In this case, the most relevant event handler
would be one that proxies appropriate keydown events to
become click events, so that you can activate the button both
with keyboard and by clicking.
In addition to any default visual styling provided for taco-button
elements, the visual styling will also need to be updated to reflect changes in logical state,
such as becoming disabled; that is, whatever style sheet has rules for taco-button will also need to have rules for taco-button[disabled].
With these points in mind, a full-featured taco-button that took on the
responsibility of conveying button semantics (including the ability to be disabled) might look
something like this:
class TacoButton extends HTMLElement {
static observedAttributes = [ "disabled" ];
constructor() {
super ();
this . _internals = this . attachInternals();
this . _internals. role = "button" ;
this . addEventListener( "keydown" , e => {
if ( e. code === "Enter" || e. code === "Space" ) {
this . dispatchEvent( new PointerEvent( "click" , {
bubbles: true ,
cancelable: true
}));
}
});
this . addEventListener( "click" , e => {
if ( this . disabled) {
e. preventDefault();
e. stopImmediatePropagation();
}
});
this . _observer = new MutationObserver(() => {
this . _internals. ariaLabel = this . textContent;
});
}
connectedCallback() {
this . setAttribute( "tabindex" , "0" );
this . _observer. observe( this , {
childList: true ,
characterData: true ,
subtree: true
});
}
disconnectedCallback() {
this . _observer. disconnect();
}
get disabled() {
return this . hasAttribute( "disabled" );
}
set disabled( flag) {
this . toggleAttribute( "disabled" , Boolean( flag));
}
attributeChangedCallback( name, oldValue, newValue) {
// name will always be "disabled" due to observedAttributes
if ( this . disabled) {
this . removeAttribute( "tabindex" );
this . _internals. ariaDisabled = "true" ;
} else {
this . setAttribute( "tabindex" , "0" );
this . _internals. ariaDisabled = "false" ;
}
}
}
Even with this rather-complicated element definition, the element is not a pleasure to use for
consumers: it will be continually "sprouting" tabindex
attributes of its own volition, and its choice of tabindex="0" focusability
behavior may not match the button behavior on the current platform. This is because
as of now there is no way to specify default focus behavior for custom elements, forcing the use
of the tabindex attribute to do so (even though it is usually
reserved for allowing the consumer to override default behavior).
In contrast, a simple customized built-in element, as shown in the previous
section, would automatically inherit the semantics and behavior of the button
element, with no need to implement these behaviors manually. In general, for any elements with
nontrivial behavior and semantics that build on top of existing elements of HTML, customized built-in elements will be easier to
develop, maintain, and consume.
This section is non-normative.
Because element definition can occur at any time, a non-custom element could be created, and then later become a custom element after an appropriate definition is registered. We call this process "upgrading" the element, from a normal element into a custom element.
Upgrades enable scenarios where it may be
preferable for custom element definitions to be
registered after relevant elements have been initially created, such as by the parser. They allow
progressive enhancement of the content in the custom element. For example, in the following HTML
document the element definition for img-viewer is loaded
asynchronously:
The definition for the img-viewer element here is loaded using a
script element marked with the async
attribute, placed after the <img-viewer> tag in the markup. While the
script is loading, the img-viewer element will be treated as an undefined
element, similar to a span. Once the script loads, it will define the img-viewer element, and the existing img-viewer element on
the page will be upgraded, applying the custom element's definition (which presumably includes
applying an image filter identified by the string "Kelvin", enhancing the image's visual
appearance).
Note that upgrades only apply to elements in the document tree. (Formally, elements that are connected.) An element that is not inserted into a document will stay un-upgraded. An example illustrates this point:
Built-in elements provided by user agents have certain states that can change over time
depending on user interaction and other factors, and are exposed to web authors through pseudo-classes. For example, some form controls have the "invalid"
state, which is exposed through the :invalid
pseudo-class.
Like built-in elements, custom elements can have various states to be in too, and custom element authors want to expose these states in a similar fashion as the built-in elements.
This is done via the :state() pseudo-class. A custom
element author can use the states property of
ElementInternals to add and remove such custom states, which are then exposed as
arguments to the :state() pseudo-class.
When authoring custom element constructors, authors are bound by the following conformance requirements:
A parameter-less call to super() must be the first statement in the
constructor body, to establish the correct prototype chain and this value before any
further code is run.
A return statement must not appear anywhere inside the constructor
body, unless it is a simple early-return (return or return
this).
The constructor must not use the document.write()
or document.open() methods.
The element's attributes and children must not be inspected, as in the non-upgrade case none will be present, and relying on upgrades makes the element less usable.
The element must not gain any attributes or children, as this violates the expectations of
consumers who use the createElement or createElementNS methods.
In general, work should be deferred to connectedCallback as much as
possible—especially work involving fetching resources or rendering. However, note that connectedCallback can be called more than once, so any initialization work that
is truly one-time will need a guard to prevent it from running twice.
In general, the constructor should be used to set up initial state and default values, and to set up event listeners and possibly a shadow root.
Several of these requirements are checked during element creation, either directly or indirectly, and failing to follow them will result in a custom element that cannot be instantiated by the parser or DOM APIs. This is true even if the work is done inside a constructor-initiated microtask, as a microtask checkpoint can occur immediately after construction.
When authoring custom element reactions, authors should avoid manipulating the node tree as this can lead to unexpected results.
A custom element is an element that is custom. Informally, this means that its constructor and prototype are defined by the author, instead of by the user agent. This author-supplied constructor function is called the custom element constructor.
Two distinct types of custom elements can be defined:
A customized built-in element, which is defined with an extends option. These types of custom
elements have a local name equal to the value passed in their extends option, and their defined name is used as the value of the
is attribute, which
therefore must be a valid custom element name.
After a custom element is created,
changing the value of the is attribute does not
change the element's behavior, as it is saved on the element as its is value.
Autonomous custom elements have the following element definition:
is attributeform, for form-associated custom elements — Associates the element with a form element
disabled, for form-associated custom elements — Whether the form control is disabled
readonly, for form-associated custom elements — Affects willValidate, plus any behavior added by the custom element author
name, for form-associated custom elements — Name of the element to use for form submission and in the form.elements API
HTMLElement)An autonomous custom element does not have any special meaning: it represents its children. A customized built-in element inherits the semantics of the element that it extends.
Any namespace-less attribute that is relevant to the element's functioning, as determined by
the element's author, may be specified on an autonomous custom element, so long as
the attribute name is XML-compatible and contains no ASCII upper alphas. The exception is the is attribute,
which must not be specified on an autonomous custom element (and which will have no
effect if it is).
Customized built-in elements follow the
normal requirements for attributes, based on the elements they extend. To add custom
attribute-based behavior, use data-* attributes.
The name attribute represents the form-associated
custom element's name. The disabled attribute is
used to make the form-associated custom element non-interactive and to prevent its
submission value from being submitted. The form attribute is used to explicitly associate the
form-associated custom element with its form owner.
Constraint validation: If the readonly attribute is specified on a form-associated
custom element, the element is barred from constraint validation.
The reset algorithm for form-associated custom elements is to enqueue
a custom element callback reaction with the element, callback name "formResetCallback", and « ».
CustomElementRegistry interfaceSupport in all current engines.
Each Window object has an associated custom element registry (a
CustomElementRegistry object). It is set to a new
CustomElementRegistry object when the Window object is created.
Support in all current engines.
The customElements attribute of the
Window interface must return the CustomElementRegistry object for that
Window object.
Element definition is a process of adding a custom element definition
to the CustomElementRegistry. This is accomplished by the define() method. The define(name, constructor,
options) method steps are:
If IsConstructor(constructor) is false, then throw a
TypeError.
If name is not a valid custom element name, then throw a
"SyntaxError" DOMException.
If this's custom element definition set contains an item with name name, then throw a
"NotSupportedError" DOMException.
If this's custom element definition set contains an item with constructor constructor,
then throw a "NotSupportedError" DOMException.
Let localName be name.
Let extends be options["extends"] if it exists; otherwise null.
If extends is not null:
If extends is a valid custom element name, then throw a
"NotSupportedError" DOMException.
If the element interface for extends and the HTML
namespace is HTMLUnknownElement (e.g., if extends does not
indicate an element definition in this specification), then throw a
"NotSupportedError" DOMException.
Set localName to extends.
If this's element definition is running is true, then throw
a "NotSupportedError" DOMException.
Set this's element definition is running to true.
Let formAssociated be false.
Let disableInternals be false.
Let disableShadow be false.
Let observedAttributes be an empty sequence<DOMString>.
Run the following steps while catching any exceptions:
Let prototype be ? Get(constructor, "prototype").
If prototype is not an Object, then throw a
TypeError exception.
Let lifecycleCallbacks be the ordered map «[ "connectedCallback" → null, "disconnectedCallback" →
null, "adoptedCallback" → null, "attributeChangedCallback" → null ]».
For each callbackName of the keys of lifecycleCallbacks:
Let callbackValue be ? Get(prototype, callbackName).
If callbackValue is not undefined, then set
lifecycleCallbacks[callbackName] to the result of converting callbackValue to the Web IDL Function callback type.
If lifecycleCallbacks["attributeChangedCallback"] is not
null:
Let observedAttributesIterable be ? Get(constructor, "observedAttributes").
If observedAttributesIterable is not undefined, then set
observedAttributes to the result of converting observedAttributesIterable to a
sequence<DOMString>. Rethrow any exceptions from the
conversion.
Let disabledFeatures be an empty sequence<DOMString>.
Let disabledFeaturesIterable be ? Get(constructor, "disabledFeatures").
If disabledFeaturesIterable is not undefined, then set
disabledFeatures to the result of converting disabledFeaturesIterable to a sequence<DOMString>. Rethrow any exceptions from the conversion.
If disabledFeatures contains "internals", then set disableInternals to true.
If disabledFeatures contains "shadow", then set disableShadow to true.
Let formAssociatedValue be ? Get( constructor, "formAssociated").
Set formAssociated to the result of converting formAssociatedValue to a boolean.
If formAssociated is true, then for each callbackName of « "formAssociatedCallback", "formResetCallback", "formDisabledCallback", "formStateRestoreCallback"
»:
Let callbackValue be ? Get(prototype, callbackName).
If callbackValue is not undefined, then set
lifecycleCallbacks[callbackName] to the result of converting callbackValue to the Web IDL Function callback type.
Then, regardless of whether the above steps threw an exception or not: set this's element definition is running to false.
Finally, if the steps threw an exception, rethrow that exception.
Let definition be a new custom element definition with name name, local name localName, constructor constructor, observed attributes observedAttributes, lifecycle callbacks lifecycleCallbacks, form-associated formAssociated, disable internals disableInternals, and disable shadow disableShadow.
Append definition to this's custom element definition set.
Let document be this's relevant global object's associated Document.
Let upgradeCandidates be all elements that are shadow-including descendants of document, whose namespace
is the HTML namespace and whose local name is localName, in
shadow-including tree order. Additionally, if extends is non-null, only
include elements whose is
value is equal to name.
For each element element of upgradeCandidates, enqueue a custom element upgrade reaction given element and definition.
If this's when-defined promise map[name] exists:
Resolve this's when-defined promise map[name] with constructor.
Remove this's when-defined promise map[name].
A custom element possesses the ability to respond to certain occurrences by running author code:
When upgraded, its constructor is run, with no arguments.
When it becomes connected, its connectedCallback is
called, with no arguments.
When it becomes disconnected, its disconnectedCallback
is called, with no arguments.
When it is adopted into a new document, its adoptedCallback is called, given the old document and new document as
arguments.
When any of its attributes are changed, appended, removed, or replaced, its attributeChangedCallback is called, given the attribute's local name, old value,
new value, and namespace as arguments. (An attribute's old or new value is considered to be null
when the attribute is added or removed, respectively.)
When the user agent resets the form owner of a
form-associated custom element and doing so changes the form owner, its formAssociatedCallback is called, given the new form owner (or null if no owner)
as an argument.
When the form owner of a form-associated custom element is reset, its formResetCallback is
called.
When the disabled state of a
form-associated custom element is changed, its formDisabledCallback is called, given the new state as an
argument.
When user agent updates a form-associated custom element's value on behalf of
a user or as part of navigation, its formStateRestoreCallback is called, given the new state and a string indicating
a reason, "autocomplete" or "restore", as
arguments.
The way in which custom element reactions are invoked is done with special care, to avoid running author code during the middle of delicate operations. Effectively, they are delayed until "just before returning to user script". This means that for most purposes they appear to execute synchronously, but in the case of complicated composite operations (like cloning, or range manipulation), they will instead be delayed until after all the relevant user agent processing steps have completed, and then run together as a batch.
Additionally, the precise ordering of these reactions is managed via a somewhat-complicated stack-of-queues system, described below. The intention behind this system is to guarantee that custom element reactions always are invoked in the same order as their triggering actions, at least within the local context of a single custom element. (Because custom element reaction code can perform its own mutations, it is not possible to give a global ordering guarantee across multiple elements.)
Each similar-origin window agent has a custom element reactions stack, which is initially empty. A similar-origin window agent's current element queue is the element queue at the top of its custom element reactions stack. Each item in the stack is an element queue, which is initially empty as well. Each item in an element queue is an element. (The elements are not necessarily custom yet, since this queue is used for upgrades as well.)
Each custom element reactions stack has an associated backup element
queue, which is an initially-empty element queue. Elements are pushed onto the
backup element queue during operations that affect the DOM without going through an
API decorated with [CEReactions], or through the parser's
create an element for the token algorithm. An example of this is a user-initiated
editing operation which modifies the descendants or attributes of an editable
element. To prevent reentrancy when processing the backup element queue, each
custom element reactions stack also has a processing the backup element
queue flag, initially unset.
This is all summarized in the following schematic diagram:
The [CEReactions] extended attribute must take no
arguments, and must not appear on anything other than an operation, attribute, setter, or deleter.
Additionally, it must not appear on readonly attributes.
Operations, attributes, setters, or deleters annotated with the [CEReactions] extended attribute must run the following steps in place
of the ones specified in their description:
Push a new element queue onto this object's relevant agent's custom element reactions stack.
Run the originally-specified steps for this construct, catching any exceptions. If the steps return a value, let value be the returned value. If they throw an exception, let exception be the thrown exception.
Let queue be the result of popping from this object's relevant agent's custom element reactions stack.
Invoke custom element reactions in queue.
If an exception exception was thrown by the original steps, rethrow exception.
If a value value was returned from the original steps, return value.
Any nonstandard APIs introduced by the user agent that could modify the DOM in such a way as to
cause enqueuing a custom element
callback reaction or enqueuing a
custom element upgrade reaction, for example by modifying any attributes or child elements,
must also be decorated with the [CEReactions] attribute.
Certain capabilities are meant to be available to a custom element author, but not to a custom
element consumer. These are provided by the element.attachInternals() method, which returns an instance of
ElementInternals. The properties and methods of ElementInternals allow
control over internal features which the user agent provides to all elements.
Each HTMLElement has an attached internals (null or an
ElementInternals object), initially null.
Support in all current engines.
ElementInternals interfaceSupport in all current engines.
The IDL for the ElementInternals interface is as follows, with the various operations and attributes
defined in the following sections:
Each ElementInternals has a target element,
which is a custom element.
Support in all current engines.
The setFormValue() method is used by
the custom element author to set the element's submission
value and state, thus communicating these to the user
agent.
When the user agent believes it is a good idea to restore a form-associated custom
element's state, for example after navigation or restarting the user agent, they may enqueue a
custom element callback reaction with that element, callback name "formStateRestoreCallback", and « the state to be restored, "restore" ».
If the user agent has a form-filling assist feature, then when the feature is invoked, it may
enqueue a custom element callback reaction with a form-associated custom
element, callback name "formStateRestoreCallback", and « the state
value determined by history of state value and some heuristics, "autocomplete" ».
In general, the state is information specified by a user, and the submission value is a value after canonicalization or sanitization, suitable for submission to the server. The following examples makes this concrete:
Support in all current engines.
Each form-associated custom element has validity flags named
valueMissing, typeMismatch,
patternMismatch, tooLong,
tooShort, rangeUnderflow,
rangeOverflow, stepMismatch, and
customError. They are false initially.
Each form-associated custom element has a validation anchor element. It is null initially.
Support in all current engines.
ElementInternals/validationMessage
Support in all current engines.
Each custom element has an internal content attribute map, which is a map, initially empty. See the Requirements related to ARIA and to platform accessibility APIs section for information on how this impacts platform accessibility APIs.
Each custom element has a states set, which is a
CustomStateSet, initially empty.
The states getter steps are to return
this's target element's states
set.
This specification does not provide a machine-readable way of describing breadcrumb navigation
menus. Authors are encouraged to just use a series of links in a paragraph. The nav
element can be used to mark the section containing these paragraphs as being navigation
blocks.
This specification does not define any markup specifically for marking up lists
of keywords that apply to a group of pages (also known as tag clouds). In general, authors
are encouraged to either mark up such lists using ul elements with explicit inline
counts that are then hidden and turned into a presentational effect using a style sheet, or to use
SVG.
This specification does not define a specific element for marking up conversations, meeting minutes, chat transcripts, dialogues in screenplays, instant message logs, and other situations where different players take turns in discourse.
Instead, authors are encouraged to mark up conversations using p elements and
punctuation. Authors who need to mark the speaker for styling purposes are encouraged to use
span or b. Paragraphs with their text wrapped in the i
element can be used for marking up stage directions.
HTML does not have a dedicated mechanism for marking up footnotes. Here are the suggested alternatives.
For short inline annotations, the title attribute could be used.
For longer annotations, the a element should be used, pointing to an element later
in the document. The convention is that the contents of the link be a number in square
brackets.
For side notes, longer annotations that apply to entire sections of the text rather than just
specific words or sentences, the aside element should be used.
For figures or tables, footnotes can be included in the relevant figcaption or
caption element, or in surrounding prose.
CSS Values and Units leaves the case-sensitivity of attribute names for the purpose of the 'attr()' function to be defined by the host language. [CSSVALUES]
When comparing the attribute name part of a CSS 'attr()' function to the names of namespace-less attributes on HTML elements in HTML documents, the name part of the CSS 'attr()' function must first be converted to ASCII lowercase. The same function when compared to other attributes must be compared according to its original case. In both cases, to match the values must be identical to each other (and therefore the comparison is case sensitive).
Selectors leaves the case-sensitivity of element names, attribute names, and attribute values to be defined by the host language. [SELECTORS]
When comparing a CSS element type selector to the names of HTML elements in HTML documents, the CSS element type selector must first be converted to ASCII lowercase. The same selector when compared to other elements must be compared according to its original case. In both cases, to match the values must be identical to each other (and therefore the comparison is case sensitive).
When comparing the name part of a CSS attribute selector to the names of attributes on HTML elements in HTML documents, the name part of the CSS attribute selector must first be converted to ASCII lowercase. The same selector when compared to other attributes must be compared according to its original case. In both cases, the comparison is case-sensitive.
Attribute selectors on an HTML element in an HTML document must treat the values of attributes with the following names as ASCII case-insensitive:
accept
accept-charset
align
alink
axis
bgcolor
charset
checked
clear
codetype
color
compact
declare
defer
dir
direction
disabled
enctype
face
frame
hreflang
http-equiv
lang
language
link
media
method
multiple
nohref
noresize
noshade
nowrap
readonly
rel
rev
rules
scope
scrolling
selected
shape
target
text
type
valign
valuetype
vlink
All other attribute values and everything else must be treated as entirely identical to each other for the purposes of selector matching. This includes:
IDs and classes in no-quirks mode and limited-quirks mode
the names of elements not in the HTML namespace
the names of HTML elements in XML documents
the names of attributes of elements not in the HTML namespace
the names of attributes of HTML elements in XML documents
the names of attributes that themselves have namespaces
There are a number of dynamic selectors that can be used with HTML. This section defines when these selectors match HTML elements. [SELECTORS] [CSSUI]
:definedSupport in all current engines.
The :defined pseudo-class must match
any element that is defined.
:linkSupport in all current engines.
All a elements that have an href
attribute, and all area elements that have an href attribute, must match one of :link and :visited.
Other specifications might apply more specific rules regarding how these elements are to match these pseudo-classes, to mitigate some privacy concerns that apply with straightforward implementations of this requirement.
:activeSupport in all current engines.
The :active pseudo-class is defined to
match an element .
To determine whether a particular element is being
activated for the purposes of defining the :active
pseudo-class only, an HTML user agent must use the first relevant entry in the
following list.
button elementinput element whose type attribute is in the Submit Button, Image Button, Reset
Button, or Button statea element that has an href attributearea element that has an href attributeThe element is being activated if it is in a formal activation state.
The element is being activated.
Additionally, any element that is the labeled control of a label
element that is currently matching :active, also matches
:active. (But, it does not count as being being activated.)
:hoverSupport in all current engines.
The :hover pseudo-class is defined to
match an element while the user
designates an element with a pointing
device
. For the purposes of defining the :hover
pseudo-class only, an HTML user agent must consider an element as being one that
the user designates if it is an element that the user
indicates using a pointing device.
Additionally, any element that is the labeled control of a label
element that is currently matching :hover, also matches
:hover. (But, it does not count as being designated.)
:focusSupport in all current engines.
:targetSupport in all current engines.
For the purposes of the CSS :target
pseudo-class, the Document's target elements are a list
containing the Document's target element, if it is not null, or
containing no elements, if it is. [SELECTORS]
:popover-openSupport in all current engines.
The :popover-open pseudo-class is
defined to match any HTML element whose popover attribute is not in the no popover state and whose popover visibility
state is showing.
:enabledSupport in all current engines.
The :enabled pseudo-class must match any
button, input, select, textarea,
optgroup, option, fieldset element, or
form-associated custom element that is not actually disabled.
:disabledSupport in all current engines.
The :disabled pseudo-class must match
any element that is actually disabled.
:checkedSupport in all current engines.
The :checked pseudo-class must match any
element falling into one of the following categories:
input elements whose type attribute is in
the Checkbox state and whose checkedness state is trueinput elements whose type attribute is in
the Radio Button state and whose checkedness state is trueoption elements whose selectedness is true:indeterminateSupport in all current engines.
The :indeterminate pseudo-class
must match any element falling into one of the following categories:
input elements whose type attribute is in
the Checkbox state and whose indeterminate IDL attribute is set to trueinput elements whose type attribute is in
the Radio Button state and whose radio button
group contains no input elements whose checkedness state is true.progress elements with no value
content attribute:defaultSupport in all current engines.
The :default pseudo-class must match any
element falling into one of the following categories:
input elements to which the checked
attribute applies and that have a checked
attributeoption elements that have a selected
attribute:placeholder-shownThe :placeholder-shown
pseudo-class must match any element falling into one of the following
categories:
input elements that have a placeholder attribute whose value is currently being
presented to the usertextarea elements that have a placeholder attribute whose value is currently being
presented to the user:validSupport in all current engines.
The :valid pseudo-class must match any
element falling into one of the following categories:
form elements that are not the form owner of any elements that
themselves are candidates for constraint
validation but do not satisfy their
constraintsfieldset elements that have no descendant elements that themselves are candidates for constraint validation but do
not satisfy their constraints:invalidSupport in all current engines.
The :invalid pseudo-class must match any
element falling into one of the following categories:
form elements that are the form owner of one or more elements
that themselves are candidates for constraint
validation but do not satisfy their
constraintsfieldset elements that have of one or more descendant elements that themselves
are candidates for constraint
validation but do not satisfy their
constraints:user-validThe :user-valid pseudo-class must
match input, textarea, and select elements whose
user validity is true, are
candidates for constraint validation,
and that satisfy their constraints.
:user-invalidThe :user-invalid pseudo-class must
match input, textarea, and select elements whose
user validity is true, are
candidates for constraint validation
but do not satisfy their constraints.
:in-rangeSupport in all current engines.
The :in-range pseudo-class must match
all elements that are candidates for
constraint validation, have range limitations, and that are neither
suffering from an underflow nor suffering from an overflow.
:out-of-rangeSupport in all current engines.
The :out-of-range pseudo-class must
match all elements that are candidates for
constraint validation, have range limitations, and that are either
suffering from an underflow or suffering from an overflow.
:requiredSupport in all current engines.
The :required pseudo-class must match
any element falling into one of the following categories:
:optionalSupport in all current engines.
The :optional pseudo-class must match
any element falling into one of the following categories:
:autofillThe :autofill and :-webkit-autofill pseudo-classes must match input elements which have
been autofilled by user agent. These pseudo-classes must stop matching if the user edits the
autofilled field.
:read-onlySupport in all current engines.
The :read-write pseudo-class must
match any element falling into one of the following categories, which for the purposes of
Selectors are thus considered user-alterable: [SELECTORS]
input elements to which the readonly
attribute applies, and that are mutable (i.e. that do not
have the readonly attribute specified and that are not
disabled)textarea elements that do not have a readonly attribute, and that are not disabledinput elements nor textarea elementsThe :read-only pseudo-class must match
all other HTML elements.
:modalThe :modal pseudo-class must match any
element falling into one of the following categories:
dialog elements whose is modal is true:dir(ltr)The :dir(ltr) pseudo-class must match all
elements whose directionality is 'ltr'.
:dir(rtl)The :dir(rtl) pseudo-class must match all
elements whose directionality is 'rtl'.
The :state(identifier) pseudo-class must
match all custom elements whose states set's set entries
contains identifier.
:playingThe :playing pseudo-class must match all
media elements whose paused attribute is false.
:pausedThe :paused pseudo-class must match all
media elements whose paused attribute is true.
:seekingThe :seeking pseudo-class must match all
media elements whose seeking attribute is true.
:bufferingThe :buffering pseudo-class must match
all media elements whose paused attribute is false, networkState attribute is NETWORK_LOADING, and ready state is HAVE_CURRENT_DATA or less.
:stalledThe :stalled pseudo-class must match
all media elements that match the :buffering pseudo-class and whose is
currently stalled is true.
:mutedThe :muted pseudo-class must match all
media elements that are muted.
:volume-lockedThe :volume-locked pseudo-class
must match all media elements when the user agent's
volume locked is true.
:openThe :open pseudo-class must match any
element falling into one of the following categories:
select elements that are a drop-down box and whose drop-down
boxes are open
input elements that support a
picker and whose pickers are open
This section is non-normative.
Sometimes, it is desirable to annotate content with specific machine-readable labels, e.g. to allow generic scripts to provide services that are customized to the page, or to enable content from a variety of cooperating authors to be processed by a single script in a consistent manner.
For this purpose, authors can use the microdata features described in this section. Microdata allows nested groups of name-value pairs to be added to documents, in parallel with the existing content.
This section is non-normative.
At a high level, microdata consists of a group of name-value pairs. The groups are called items, and each name-value pair is a property. Items and properties are represented by regular elements.
To create an item, the itemscope attribute is used.
To add a property to an item, the itemprop attribute is used
on one of the item's descendants.
Markup without the microdata-related attributes does not have any effect on the microdata model.
Properties generally have values that are strings.
When a string value is a URL, it is expressed using the a element and
its href attribute, the img element and its
src attribute, or other elements that link to or embed external
resources.
When a string value is in some machine-readable format unsuitable for human consumption, it is
expressed using the value attribute of the data
element, with the human-readable version given in the element's contents.
For numeric data, the meter element and its value attribute can be used instead.
Similarly, for date- and time-related data, the time element and its datetime attribute can be used instead.
Properties can also themselves be groups of name-value pairs, by putting the itemscope attribute on the element that declares the property.
Items that are not part of others are called top-level microdata items.
Properties that are not descendants of the element with the itemscope attribute can be associated with the item using the itemref attribute.
This attribute takes a list of IDs of elements to crawl in addition to crawling the children of
the element with the itemscope attribute.
An item can have multiple properties with the same name and different values.
An element introducing a property can also introduce multiple properties at once, to avoid duplication when some of the properties have the same value.
It's important to note that there is no relationship between the microdata and the content of the document where the microdata is marked up.
This section is non-normative.
The examples in the previous section show how information could be marked up on a page that doesn't expect its microdata to be re-used. Microdata is most useful, though, when it is used in contexts where other authors and readers are able to cooperate to make new uses of the markup.
For this purpose, it is necessary to give each item a type, such as "https://example.com/person", or "https://example.org/cat", or "https://band.example.net/". Types are identified as URLs.
The type for an item is given as the value of an itemtype attribute on the same element as the itemscope attribute.
The type gives the context for the properties, thus selecting a vocabulary: a property named
"class" given for an item with the type "https://census.example/person" might refer to the economic
class of an individual, while a property named "class" given for an item with the type
"https://example.com/school/teacher" might refer to the classroom a teacher has been assigned.
Several types can share a vocabulary. For example, the types "https://example.org/people/teacher" and "https://example.org/people/engineer" could be defined to use the same vocabulary
(though maybe some properties would not be especially useful in both cases, e.g. maybe the "https://example.org/people/engineer" type might not typically be used with the
"classroom" property). Multiple types defined to use the same vocabulary can
be given for a single item by listing the URLs as a space-separated list in the attribute' value.
An item cannot be given two types if they do not use the same vocabulary, however.
This section is non-normative.
Sometimes, an item gives information about a topic that has a global identifier. For example, books can be identified by their ISBN number.
Vocabularies (as identified by the itemtype attribute) can
be designed such that items get associated with their global
identifier in an unambiguous way by expressing the global identifiers as URLs given in an itemid attribute.
The exact meaning of the URLs given in itemid attributes depends on the vocabulary used.
This section is non-normative.
Using microdata means using a vocabulary. For some purposes, an ad-hoc vocabulary is adequate. For others, a vocabulary will need to be designed. Where possible, authors are encouraged to re-use existing vocabularies, as this makes content re-use easier.
When designing new vocabularies, identifiers can be created either using URLs, or, for properties, as plain words (with no dots or colons). For URLs, conflicts with other vocabularies can be avoided by only using identifiers that correspond to pages that the author has control over.
Properties whose names are just plain words can only be used within the context of the types for which they are intended; properties named using URLs can be reused in items of any type. If an item has no type, and is not part of another item, then if its properties have names that are just plain words, they are not intended to be globally unique, and are instead only intended for limited use. Generally speaking, authors are encouraged to use either properties with globally unique names (URLs) or ensure that their items are typed.
The microdata model consists of groups of name-value pairs known as items.
Each group is known as an item. Each item can have item types, a global identifier (if the vocabulary specified by the item types support global identifiers for items), and a list of name-value pairs. Each name in the name-value pair is known as a property, and each property has one or more values. Each value is either a string or itself a group of name-value pairs (an item). The names are unordered relative to each other, but if a particular name has multiple values, they do have a relative order.
Support in all current engines.
An element with the itemscope attribute specified creates a
new item, a group of name-value pairs.
Support in all current engines.
The itemtype attribute, if specified, must have a value that
is an unordered set of unique space-separated tokens, none of which are
identical to another token and each of which is a valid URL string that
is an absolute URL, and all of which are defined to use the same vocabulary. The
attribute's value must have at least one token.
The item types must all be types defined in applicable specifications and must all be defined to use the same vocabulary.
Except if otherwise specified by that specification, the URLs given as the item types should not be automatically dereferenced.
Item types are opaque identifiers, and user agents must not dereference unknown item types, or otherwise deconstruct them, in order to determine how to process items that use them.
The itemtype attribute must not be specified on elements
that do not have an itemscope attribute specified.
An item is said to be a typed item when either it has an item type, or it is the value of a property of a typed item. The relevant types for a typed item is the item's item types, if it has any, or else is the relevant types of the item for which it is a property's value.
Support in all current engines.
Elements with an itemscope attribute and an itemtype attribute that references a vocabulary that is defined to
support global identifiers for items may also have an itemid attribute specified, to give a
global identifier for the item, so that it can be related to
other items on pages elsewhere on the web.
The itemid attribute, if specified, must have a value that is
a valid URL potentially surrounded by spaces.
The itemid attribute must not be specified on elements that do
not have both an itemscope attribute and an itemtype attribute specified, and must not be specified on elements
with an itemscope attribute whose itemtype attribute specifies a vocabulary that does not support
global identifiers for items, as defined by that vocabulary's specification.
The exact meaning of a global identifier is determined by the vocabulary's specification. It is up to such specifications to define whether multiple items with the same global identifier (whether on the same page or on different pages) are allowed to exist, and what the processing rules for that vocabulary are with respect to handling the case of multiple items with the same ID.
Support in all current engines.
The itemref attribute, if specified, must have a value that
is an unordered set of unique space-separated tokens none of which are
identical to another token and consisting of IDs of
elements in the same tree.
The itemref attribute must not be specified on elements that
do not have an itemscope attribute specified.
itemprop attributeSupport in all current engines.
Every HTML element may have an itemprop attribute specified, if doing so adds one or more properties to one or more items (as defined below).
The itemprop attribute, if specified, must have a value
that is an unordered set of unique space-separated tokens none of which are
identical to another token, representing the names of the name-value pairs that it
adds. The attribute's value must have at least one token.
Each token must be either:
Specifications that introduce defined property names must ensure all such property names contain no U+002E FULL STOP characters (.), no U+003A COLON characters (:), and no ASCII whitespace.
When an element with an itemprop attribute adds a property to multiple items,
the requirement above regarding the tokens applies for each item
individually.
Within an item, the properties are unordered with respect to each other, except for properties with the same name, which are ordered in the order they are given by the algorithm that defines the properties of an item.
If a property's value, as defined by the property's definition, is an absolute URL, the property must be specified using a URL property element.
All itemref attributes in a Document must be
such that there are no cycles in the graph formed from representing each item in the Document as a node in the graph and each
property of an item whose value is another item as an edge in the graph connecting
those two items.
A document must not contain any elements that have an itemprop attribute that would not be found to be a property of any of
the items in that document were their properties all to be determined.
Currently, the itemscope, itemprop, and other microdata attributes are only defined for
HTML elements. This means that attributes with the literal names "itemscope", "itemprop", etc, do not cause microdata
processing to occur on elements in other namespaces, such as SVG.
The vocabularies in this section are primarily intended to demonstrate how a vocabulary is specified, though they are also usable in their own right.
This vocabulary does not support global identifiers for items.
The following are the type's defined property names. They are based on the vocabulary defined in vCard Format Specification (vCard) and its extensions, where more information on how to interpret the values can be found. [RFC6350]
kindDescribes what kind of contact the item represents.
The value must be text that is identical to one of the kind strings.
A single property with the name kind may be present within
each item with the type http://microformats.org/profile/hcard.
fnGives the formatted text corresponding to the name of the person or organization.
The value must be text.
Exactly one property with the name fn must be present within
each item with the type http://microformats.org/profile/hcard.
nGives the structured name of the person or organization.
The value must be an item with zero or more of each of the family-name, given-name, additional-name, honorific-prefix, and honorific-suffix properties.
Exactly one property with the name n must be present within
each item with the type http://microformats.org/profile/hcard.
family-name (inside n)Gives the family name of the person, or the full name of the organization.
The value must be text.
Any number of properties with the name family-name may be present within the item that forms the value of the n property of
an item with the type http://microformats.org/profile/hcard.
given-name (inside n)Gives the given-name of the person.
The value must be text.
Any number of properties with the name given-name
may be present within the item that forms the value of the n property of
an item with the type http://microformats.org/profile/hcard.
additional-name (inside n)Gives the any additional names of the person.
The value must be text.
Any number of properties with the name additional-name may be present within the item that forms the value of the n property of
an item with the type http://microformats.org/profile/hcard.
honorific-prefix (inside n)Gives the honorific prefix of the person.
The value must be text.
Any number of properties with the name honorific-prefix may be present within the item that forms the value of the n property of
an item with the type http://microformats.org/profile/hcard.
honorific-suffix (inside n)Gives the honorific suffix of the person.
The value must be text.
Any number of properties with the name honorific-suffix may be present within the item that forms the value of the n property of
an item with the type http://microformats.org/profile/hcard.
nicknameGives the nickname of the person or organization.
The value must be text.
Any number of properties with the name nickname may be
present within each item with the type http://microformats.org/profile/hcard.
photoGives a photograph of the person or organization.
The value must be an absolute URL.
Any number of properties with the name photo may be
present within each item with the type http://microformats.org/profile/hcard.
bdayGives the birth date of the person or organization.
The value must be a valid date string.
A single property with the name bday may be present within
each item with the type http://microformats.org/profile/hcard.
anniversaryGives the birth date of the person or organization.
The value must be a valid date string.
A single property with the name anniversary may be
present within each item with the type http://microformats.org/profile/hcard.
sexGives the biological sex of the person.
The value must be one of
F, meaning "female",
M, meaning "male",
N, meaning "none or not applicable",
O, meaning "other", or
U, meaning "unknown".
A single property with the name sex may be present within
each item with the type http://microformats.org/profile/hcard.
gender-identityGives the gender identity of the person.
The value must be text.
A single property with the name gender-identity
may be present within each item with the type http://microformats.org/profile/hcard.
adrGives the delivery address of the person or organization.
The value must be an item with zero or more type,
post-office-box, extended-address, and street-address properties, and optionally a locality property, optionally a region property, optionally a postal-code property, and optionally a country-name property.
If no type properties are present within an item that forms the value of an adr property
of an item with the type http://microformats.org/profile/hcard, then the address type string work is
implied.
Any number of properties with the name adr may be present
within each item with the type http://microformats.org/profile/hcard.
type (inside adr)Gives the type of delivery address.
The value must be text that is identical to one of the address type strings.
Any number of properties with the name type may be
present within the item that forms the value of an adr property
of an item with the type http://microformats.org/profile/hcard, but within each such adr property item there must only
be one type property per distinct value.
post-office-box (inside adr)Gives the post office box component of the delivery address of the person or organization.
The value must be text.
Any number of properties with the name post-office-box may be present within the item that forms the value of an adr property
of an item with the type http://microformats.org/profile/hcard.
extended-address (inside adr)Gives an additional component of the delivery address of the person or organization.
The value must be text.
Any number of properties with the name extended-address may be present within the item that forms the value of an adr property
of an item with the type http://microformats.org/profile/hcard.
street-address (inside adr)Gives the street address component of the delivery address of the person or organization.
The value must be text.
Any number of properties with the name street-address may be present within the item that forms the value of an adr property
of an item with the type http://microformats.org/profile/hcard.
locality (inside adr)Gives the locality component (e.g. city) of the delivery address of the person or organization.
The value must be text.
A single property with the name locality may be
present within the item that forms the value of an adr property
of an item with the type http://microformats.org/profile/hcard.
region (inside adr)Gives the region component (e.g. state or province) of the delivery address of the person or organization.
The value must be text.
A single property with the name region may be
present within the item that forms the value of an adr property
of an item with the type http://microformats.org/profile/hcard.
postal-code (inside adr)Gives the postal code component of the delivery address of the person or organization.
The value must be text.
A single property with the name postal-code may
be present within the item that forms the value of an adr property
of an item with the type http://microformats.org/profile/hcard.
country-name (inside adr)Gives the country name component of the delivery address of the person or organization.
The value must be text.
A single property with the name country-name
may be present within the item that forms the value of an adr property
of an item with the type http://microformats.org/profile/hcard.
telGives the telephone number of the person or organization.
The value must be either text that can be
interpreted as a telephone number as defined in the CCITT specifications E.163 and X.121, or an
item with zero or more type properties and exactly one value property. [E163] [X121]
If no type properties are present within an item that forms the value of a tel property
of an item with the type http://microformats.org/profile/hcard, or if the value of such a tel
property is text, then the telephone type string
voice is implied.
Any number of properties with the name tel may be present
within each item with the type http://microformats.org/profile/hcard.
type (inside tel)Gives the type of telephone number.
The value must be text that is identical to one of the telephone type strings.
Any number of properties with the name type may be
present within the item that forms the value of a tel property
of an item with the type http://microformats.org/profile/hcard, but within each such tel property item there must only
be one type property per distinct value.
value (inside tel)Gives the actual telephone number of the person or organization.
The value must be text that can be interpreted as a telephone number as defined in the CCITT specifications E.163 and X.121. [E163] [X121]
Exactly one property with the name value must be
present within the item that forms the value of a tel property
of an item with the type http://microformats.org/profile/hcard.
emailGives the email address of the person or organization.
The value must be text.
Any number of properties with the name email may be
present within each item with the type http://microformats.org/profile/hcard.
imppGives a URL for instant messaging and presence protocol communications with the person or organization.
The value must be an absolute URL.
Any number of properties with the name impp may be present
within each item with the type http://microformats.org/profile/hcard.
langGives a language understood by the person or organization.
The value must be a valid BCP 47 language tag. [BCP47]
Any number of properties with the name lang may be present
within each item with the type http://microformats.org/profile/hcard.
tzGives the time zone of the person or organization.
The value must be text and must match the following syntax:
Any number of properties with the name tz may be present
within each item with the type http://microformats.org/profile/hcard.
geoGives the geographical position of the person or organization.
The value must be text and must match the following syntax:
The optional components marked with an asterisk (*) should be included, and should have six digits each.
Any number of properties with the name geo may be present
within each item with the type http://microformats.org/profile/hcard.
titleGives the job title, functional position or function of the person or organization.
The value must be text.
Any number of properties with the name title may be
present within each item with the type http://microformats.org/profile/hcard.
roleGives the role, occupation, or business category of the person or organization.
The value must be text.
Any number of properties with the name role may be present
within each item with the type http://microformats.org/profile/hcard.
logoGives the logo of the person or organization.
The value must be an absolute URL.
Any number of properties with the name logo may be present
within each item with the type http://microformats.org/profile/hcard.
agentGives the contact information of another person who will act on behalf of the person or organization.
The value must be either an item with the type http://microformats.org/profile/hcard, or an absolute URL,
or text.
Any number of properties with the name agent may be
present within each item with the type http://microformats.org/profile/hcard.
orgGives the name and units of the organization.
The value must be either text or an item with one organization-name property and zero or more organization-unit properties.
Any number of properties with the name org may be present
within each item with the type http://microformats.org/profile/hcard.
organization-name (inside org)Gives the name of the organization.
The value must be text.
Exactly one property with the name organization-name must be present within the item that forms the value of an org property
of an item with the type http://microformats.org/profile/hcard.
organization-unit (inside org)Gives the name of the organization unit.
The value must be text.
Any number of properties with the name organization-unit may be present within the item that forms the value of the org
property of an item with the type http://microformats.org/profile/hcard.
memberGives a URL that represents a member of the group.
The value must be an absolute URL.
Any number of properties with the name member may be
present within each item with the type http://microformats.org/profile/hcard if the item also has a property with the name kind whose value is "group".
relatedGives a relationship to another entity.
The value must be an item with one url
property and one rel properties.
Any number of properties with the name related may be
present within each item with the type http://microformats.org/profile/hcard.
url (inside related)Gives the URL for the related entity.
The value must be an absolute URL.
Exactly one property with the name url must be
present within the item that forms the value of a related
property of an item with the type http://microformats.org/profile/hcard.
rel (inside related)Gives the relationship between the entity and the related entity.
The value must be text that is identical to one of the relationship strings.
Exactly one property with the name rel must be
present within the item that forms the value of a related
property of an item with the type http://microformats.org/profile/hcard.
categoriesGives the name of a category or tag that the person or organization could be classified as.
The value must be text.
Any number of properties with the name categories
may be present within each item with the type http://microformats.org/profile/hcard.
noteGives supplemental information or a comment about the person or organization.
The value must be text.
Any number of properties with the name note may be present
within each item with the type http://microformats.org/profile/hcard.
revGives the revision date and time of the contact information.
The value must be text that is a valid global date and time string.
Any number of properties with the name rev may be present
within each item with the type http://microformats.org/profile/hcard.
soundGives a sound file relating to the person or organization.
The value must be an absolute URL.
Any number of properties with the name sound may be
present within each item with the type http://microformats.org/profile/hcard.
uidGives a globally unique identifier corresponding to the person or organization.
The value must be text.
A single property with the name uid may be present within
each item with the type http://microformats.org/profile/hcard.
urlGives a URL relating to the person or organization.
The value must be an absolute URL.
Any number of properties with the name url may be present
within each item with the type http://microformats.org/profile/hcard.
This section is non-normative.
This vocabulary does not support global identifiers for items.
The following are the type's defined property names. They are based on the vocabulary defined in Internet Calendaring and Scheduling Core Object Specification (iCalendar), where more information on how to interpret the values can be found. [RFC5545]
attachGives the address of an associated document for the event.
The value must be an absolute URL.
Any number of properties with the name attach may be
present within each item with the type http://microformats.org/profile/hcalendar#vevent.
categoriesGives the name of a category or tag that the event could be classified as.
The value must be text.
Any number of properties with the name categories
may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.
classGives the access classification of the information regarding the event.
The value must be text with one of the following values:
publicprivateconfidentialA single property with the name class may be present
within each item with the type http://microformats.org/profile/hcalendar#vevent.
commentGives a comment regarding the event.
The value must be text.
Any number of properties with the name comment may be
present within each item with the type http://microformats.org/profile/hcalendar#vevent.
descriptionGives a detailed description of the event.
The value must be text.
A single property with the name description may be
present within each item with the type http://microformats.org/profile/hcalendar#vevent.
geoGives the geographical position of the event.
The value must be text and must match the following syntax:
The optional components marked with an asterisk (*) should be included, and should have six digits each.
A single property with the name geo may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent.
locationGives the location of the event.
The value must be text.
A single property with the name location may be
present within each item with the type http://microformats.org/profile/hcalendar#vevent.
resourcesGives a resource that will be needed for the event.
The value must be text.
Any number of properties with the name resources may
be present within each item with the type http://microformats.org/profile/hcalendar#vevent.
statusGives the confirmation status of the event.
The value must be text with one of the following values:
tentativeconfirmedcanceledA single property with the name status may be present
within each item with the type http://microformats.org/profile/hcalendar#vevent.
summaryGives a short summary of the event.
The value must be text.
User agents should replace U+000A LINE FEED (LF) characters in the value by U+0020 SPACE characters when using the value.
A single property with the name summary may be present
within each item with the type http://microformats.org/profile/hcalendar#vevent.
dtendGives the date and time by which the event ends.
If the property with the name dtend is present within an
item with the type http://microformats.org/profile/hcalendar#vevent that has a property
with the name dtstart whose value is a valid date
string, then the value of the property with
the name dtend must be text that is a valid date
string also. Otherwise, the value of the
property must be text that is a valid global date and time string.
In either case, the value be later in time than
the value of the dtstart property of the same item.
A single property with the name dtend may be present
within each item with the type http://microformats.org/profile/hcalendar#vevent, so long as that http://microformats.org/profile/hcalendar#vevent does not have a
property with the name duration.
dtstartGives the date and time at which the event starts.
The value must be text that is either a valid date string or a valid global date and time string.
Exactly one property with the name dtstart must be
present within each item with the type http://microformats.org/profile/hcalendar#vevent.
durationGives the duration of the event.
The value must be text that is a valid vevent duration string.
The duration represented is the sum of all the durations represented by integers in the value.
A single property with the name duration may be
present within each item with the type http://microformats.org/profile/hcalendar#vevent, so long as that http://microformats.org/profile/hcalendar#vevent does not have a
property with the name dtend.
transpGives whether the event is to be considered as consuming time on a calendar, for the purpose of free-busy time searches.
The value must be text with one of the following values:
opaquetransparentA single property with the name transp may be present
within each item with the type http://microformats.org/profile/hcalendar#vevent.
contactGives the contact information for the event.
The value must be text.
Any number of properties with the name contact may be
present within each item with the type http://microformats.org/profile/hcalendar#vevent.
urlGives a URL for the event.
The value must be an absolute URL.
A single property with the name url may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent.
uidGives a globally unique identifier corresponding to the event.
The value must be text.
A single property with the name uid may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent.
exdateGives a date and time at which the event does not occur despite the recurrence rules.
The value must be text that is either a valid date string or a valid global date and time string.
Any number of properties with the name exdate may be
present within each item with the type http://microformats.org/profile/hcalendar#vevent.
rdateGives a date and time at which the event recurs.
The value must be text that is one of the following:
Any number of properties with the name rdate may be
present within each item with the type http://microformats.org/profile/hcalendar#vevent.
rruleGives a rule for finding dates and times at which the event occurs.
The value must be text that matches the RECUR value type defined in iCalendar. [RFC5545]
A single property with the name rrule may be
present within each item with the type http://microformats.org/profile/hcalendar#vevent.
createdGives the date and time at which the event information was first created in a calendaring system.
The value must be text that is a valid global date and time string.
A single property with the name created may be present
within each item with the type http://microformats.org/profile/hcalendar#vevent.
last-modifiedGives the date and time at which the event information was last modified in a calendaring system.
The value must be text that is a valid global date and time string.
A single property with the name last-modified
may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.
sequenceGives a revision number for the event information.
The value must be text that is a valid non-negative integer.
A single property with the name sequence may be
present within each item with the type http://microformats.org/profile/hcalendar#vevent.
This section is non-normative.
The following are the type's defined property names.
workIdentifies the work being described.
The value must be an absolute URL.
Exactly one property with the name work must be present
within each item with the type http://n.whatwg.org/work.
titleGives the name of the work.
A single property with the name title may be present
within each item with the type http://n.whatwg.org/work.
authorGives the name or contact information of one of the authors or creators of the work.
The value must be either an item with the type http://microformats.org/profile/hcard, or text.
Any number of properties with the name author may be
present within each item with the type http://n.whatwg.org/work.
licenseIdentifies one of the licenses under which the work is available.
The value must be an absolute URL.
Any number of properties with the name license may be
present within each item with the type http://n.whatwg.org/work.
This section is non-normative.
Support in one engine only.
Support in all current engines.
All may have the hidden content attribute set. The attribute is an with the
following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
hidden
| hidden | Will not be rendered. |
| (the empty string) | ||
until-found
| hidden until found | Will not be rendered, but content inside will be accessible to and . |
When an element has the attribute in the state, it indicates that the element is not yet, or is no longer, directly relevant to the page's current state, or that it is being used to declare content to be reused by other parts of the page as opposed to being directly accessed by the user. User agents should not render elements that are in the state. This requirement may be implemented indirectly through the style layer. For example, a web browser could implement these requirements using the rules suggested in the Rendering section.
When an element has the attribute in the state, it indicates that the element is hidden like the state but the content inside the element will be accessible to and . When these features attempt to scroll to a target which is in the element's subtree, the user agent will remove the attribute in order to reveal the content before scrolling to it. In addition to removing the attribute, an event named is also fired on the element before the attribute is removed.
Web browsers will use 'content-visibility: hidden' instead of 'display: none' when the attribute is in the state, as specified in the Rendering section.
The attribute must not be used to hide content that could legitimately be shown in another presentation. For example, it is incorrect to use to hide panels in a tabbed dialog, because the tabbed interface is merely a kind of overflow presentation — one could equally well just show all the form controls in one big page with a scrollbar. It is similarly incorrect to use this attribute to hide content just from one presentation — if something is marked , it is hidden from all presentations, including, for instance, screen readers.
Elements that are not themselves must not
to elements that are . The for attributes of and elements that are not
themselves must similarly not refer to elements that are
. In both cases, such references would cause user
confusion.
Elements and scripts may, however, refer to elements that are in other contexts.
Elements in a section hidden by the attribute are still active, e.g. scripts and form controls in such sections still execute and submit respectively. Only their presentation to the user changes.
Support in all current engines.
The setter steps are:
If the given value is a string that is an match for "", then set the attribute to "".
Otherwise, if the given value is false, then remove the attribute.
Otherwise, if the given value is the empty string, then remove the attribute.
Otherwise, if the given value is null, then remove the attribute.
Otherwise, if the given value is 0, then remove the attribute.
Otherwise, if the given value is NaN, then remove the attribute.
Otherwise, set the attribute to the empty string.
A traversable navigable's system visibility state, including its initial value upon creation, is determined by the user agent. It represents, for example, whether the browser window is minimized, a browser tab is currently in the background, or a system element such as a task switcher obscures the page.
When a user-agent determines that the system visibility state for traversable navigable traversable has changed to newState, it must run the following steps:
Let navigables be the inclusive descendant navigables of traversable's active document.
For each navigable of navigables :
Let document be navigable's active document.
Queue a global task on the user interaction task source given document's relevant global object to update the visibility state of document with newState.
A Document has a visibility state, which is
either "hidden" or "visible", initially set to
"hidden".
Support in all current engines.
The visibilityState getter steps are to return
this's visibility state.
Support in all current engines.
VisibilityStateEntry interfaceSupport in one engine only.
The VisibilityStateEntry interface exposes visibility changes to the document,
from the moment the document becomes active.
The duration getter steps are to return
zero.
User agents may allow the user to override the restrictions on find-in-page and text selection, however.
By default, a node is not inert.
subject can additionally become inert via the inert attribute, but only if specified on subject itself
(i.e., subject escapes inertness of ancestors); subject's flat
tree descendants can become inert in a similar fashion.
inert attributeSupport in all current engines.
The inert attribute is a boolean attribute that
indicates, by its presence, that the element and all its flat tree descendants which
don't otherwise escape inertness (such as modal dialogs) are to be made inert by the
user agent.
An inert subtree should not contain any content or controls which are critical to
understanding or using aspects of the page which are not in the inert state. Content in an inert
subtree will not be perceivable by all users, or interactive. Authors should not specify elements
as inert unless the content they represent are also visually obscured in some way. In most cases,
authors should not specify the inert attribute on individual form controls. In these
instances, the disabled attribute is probably more
appropriate.
Support in all current engines.
The inert IDL attribute
must reflect the content attribute of the same name.
To prevent abuse of certain APIs that could be annoying to users (e.g., opening popups or vibrating phones), user agents allow these APIs only when the user is actively interacting with the web page or has interacted with the page at least once. This "active interaction" state is maintained through the mechanisms defined in this section.
For the purpose of tracking user activation, each Window W has two
relevant values:
We then have the following boolean user activation states for W:
When the current high resolution time given W is greater than or equal to the last activation timestamp in W, W is said to have sticky activation.
This is W's historical activation state, indicating whether the user has ever interacted in W. It starts false, then changes to true (and never changes back to false) when W gets the very first activation notification.
When the current high resolution time given W is greater than or equal to the last activation timestamp in W, and less than the last activation timestamp in W plus the transient activation duration, then W is said to have transient activation.
This is W's current activation state, indicating whether the user has interacted in W recently. This starts with a false value, and remains true for a limited time after every activation notification W gets.
When the last history-action activation timestamp of W is not equal to the last activation timestamp of W, then W is said to have history-action activation.
This is a special variant of user activation, used to allow access to certain session history APIs which, if used too frequently, would make it harder for the user to traverse back using browser UI. It starts with a false value, and becomes true whenever the user interacts with W, but is reset to false through history-action activation consumption. This ensures such APIs cannot be used multiple times in a row without an intervening user activation. But unlike transient activation, there is no time limit within which such APIs must be used.
APIs that are dependent on user activation are classified into different levels:
These APIs require the sticky activation state to be true, so they are blocked until the very first user activation.
These APIs require the transient activation state to be true, but they don't consume it, so multiple calls are allowed per user activation until the transient state expires.
These APIs require the transient activation state to be true, and they consume user activation in each call to prevent multiple calls per user activation.
These APIs require the history-action activation state to be true, and they consume history-action user activation in each call to prevent multiple calls per user activation.
UserActivation interfaceEach Window has an associated UserActivation, which is a
UserActivation object. Upon creation of the Window object, its
associated UserActivation must be set to a new
UserActivation object created in the Window object's relevant realm.
The userActivation getter steps are to return
this's relevant global object's associated
UserActivation.
The hasBeenActive getter steps are to return
true if this's relevant global object has sticky
activation, and false otherwise.
The isActive getter steps are to return true if
this's relevant global object has transient activation,
and false otherwise.
For the purposes of user-agent automation and application testing, this specification defines the following extension command for the Web Driver specification. It is optional for a user agent to support the following extension command. [WEBDRIVER]
| HTTP Method | URI Template |
|---|---|
`POST` | /session/{session id}/window/consume-user-activation |
The remote end steps are:
Let window be current browsing context's active window.
Let consume be true if window has transient activation; otherwise false.
If consume is true, then consume user activation of window.
Return success with data consume.
Certain elements in HTML have an activation behavior, which means that the user
can activate them. This is always caused by a click event.
The user agent should allow the user to manually trigger elements that have an activation
behavior, for instance using keyboard or voice input, or through mouse clicks. When the
user triggers an element with a defined activation behavior in a manner other than
clicking it, the default action of the interaction event must be to fire a click event at the element.
ToggleEvent interfaceSupport in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
This section is non-normative.
An HTML user interface typically consists of multiple interactive widgets, such as form controls, scrollable regions, links, dialog boxes, browser tabs, and so forth. These widgets form a hierarchy, with some (e.g. browser tabs, dialog boxes) containing others (e.g. links, form controls).
When interacting with an interface using a keyboard, key input is channeled from the system, through the hierarchy of interactive widgets, to an active widget, which is said to be focused.
Keyboard events are always targeted at this focused element.
The following table describes what objects can be focusable areas. The cells in the left column describe objects that can be focusable areas; the cells in the right column describe the DOM anchors for those elements. (The cells that span both columns are non-normative examples.)
| Focusable area | DOM anchor |
|---|---|
| Examples | |
Elements that meet all the following criteria:
| The element itself. |
The shapes of area elements in an image map associated with an
img element that is being rendered and is not inert.
|
The img element.
|
| The user-agent provided subwidgets of elements that are being rendered and are not actually disabled or inert. | The element for which the focusable area is a subwidget. |
| The scrollable regions of elements that are being rendered and are not inert. | The element for which the box that the scrollable region scrolls was created. |
The viewport of a Document that has a non-null browsing context and is not inert.
|
The Document for which the viewport was created.
|
| Any other element or part of an element determined by the user agent to be a focusable area, especially to aid with accessibility or to better match platform conventions. | The element. |
An element that is the DOM anchor of a focusable area is said to gain focus when that focusable area becomes the currently focused area of a top-level traversable. When an element is the DOM anchor of a focusable area of the currently focused area of a top-level traversable, it is focused.
There are two special types of focusability for focusable areas:
When a user activates a click focusable focusable
area, the user agent must run the focusing steps on the focusable
area with focus trigger set to "click".
Then, the contents of a given focus navigation scope owner owner's focus navigation scope are all elements whose associated focus navigation owner is owner.
The order within a tabindex-ordered focus navigation scope is determined by each element's tabindex value, as described in the section below.
tabindex attributeSupport in all current engines.
The name "tab index" comes from the common use of the Tab key to navigate through the focusable elements. The term "tabbing" refers to moving forward through sequentially focusable focusable areas.
The tabindex attribute, if specified, must have a value
that is a valid integer. Positive numbers specify the relative position of the
element's focusable areas in the sequential focus
navigation order, and negative numbers indicate that the control is not
sequentially focusable.
Developers should use caution when using values other than 0 or −1 for their tabindex attributes as this is complicated to do correctly.
The tabindex value of a focusable area is the tabindex value of its DOM anchor.
The tabindex value of an element must be interpreted as follows:
The user agent should follow platform conventions to determine if the element should be considered as a focusable area and if so, whether the element and any focusable areas that have the element as their DOM anchor are sequentially focusable, and if so, what their relative position in their tabindex-ordered focus navigation scope is to be. If the element is a focus navigation scope owner, it must be included in its tabindex-ordered focus navigation scope even if it is not a focusable area.
The relative ordering within a tabindex-ordered focus navigation scope for elements and focusable areas that belong to the same focus navigation scope and whose tabindex value is null should be in shadow-including tree order.
Modulo platform conventions, it is suggested that the following elements should be considered as focusable areas and be sequentially focusable:
a elements that have an href
attributebutton elementsinput elements whose type attribute are
not in the stateselect elementstextarea elementssummary elements that are the first summary element child of a
details elementdraggable attribute set, if that would
enable the user agent to allow the user to begin drag operations for those elements without
the use of a pointing deviceThe user agent must consider the element as a focusable area, but should omit the element from any tabindex-ordered focus navigation scope.
The user agent must allow the element to be considered as a focusable area and should allow the element and any focusable areas that have the element as their DOM anchor to be sequentially focusable.
The relative ordering within a tabindex-ordered focus navigation scope for elements and focusable areas that belong to the same focus navigation scope and whose tabindex value is zero should be in shadow-including tree order.
The user agent must allow the element to be considered as a focusable area and should allow the element and any focusable areas that have the element as their DOM anchor to be sequentially focusable, and should place the element — referenced as candidate below — and the aforementioned focusable areas in the tabindex-ordered focus navigation scope where the element is a part of so that, relative to other elements and focusable areas that belong to the same focus navigation scope, they are:
tabindex attribute has been omitted or whose value, when parsed,
returns an error,tabindex attribute has a value less than or equal to zero,tabindex attribute has a value greater than zero but less than
the value of the tabindex attribute on candidate,tabindex attribute has a value equal to the value of the tabindex attribute on candidate but that is
located earlier than candidate in shadow-including tree order,tabindex attribute has a value equal to the value of the tabindex attribute on candidate but that is
located later than candidate in shadow-including tree order, andtabindex attribute has a value greater than the value of the
tabindex attribute on candidate.Support in all current engines.
The tabIndex IDL
attribute must reflect the value of the tabindex
content attribute. The default value is 0 if the element is an a,
area, button, frame, iframe,
input, object, select, textarea, or SVG
a element, or is a summary element that is a summary for
its parent details. The default value is −1 otherwise.
User agents must immediately run the focusing steps for a focusable area or navigable candidate whenever the user attempts to move the focus to candidate.
To fire a focus event named e at an element t with a given
related target r, fire an event named
e at t, using FocusEvent, with the relatedTarget attribute initialized to r,
the view attribute initialized to t's
node document's relevant global object, and the composed
flag set.
When a key event is to be routed in a top-level traversable, the user agent must run the following steps:
Let target area be the currently focused area of the top-level traversable.
Assert: target area is not null, since key events are only routed to top-level traversables that have system focus. Therefore, target area is a focusable area.
Let target node be target area's DOM anchor.
If target node is a Document that has a body element, then let target node be the body
element of that Document.
Otherwise, if target node is a Document object that has a non-null
document element, then let target node be that document
element.
If target node is not inert, then:
Let canHandle be the result of dispatching the key event at target node.
If canHandle is true, then let target area handle the key event.
This might include firing a click event at target node.
If a focusable area is omitted from the sequential focus navigation
order of its Document, then it is unreachable via sequential focus
navigation.
A sequential focus direction is one of two possible values: "forward", or "backward". They are used in the below algorithms
to describe the direction in which sequential focus travels at the user's request.
A selection mechanism is one of two possible values: "DOM", or
"sequential". They are used to
describe how the sequential navigation search algorithm finds the focusable
area it returns.
When the user requests that focus move from the currently focused area of a top-level traversable to the next or previous focusable area (e.g., as the default action of pressing the tab key), or when the user requests that focus sequentially move to a top-level traversable in the first place (e.g., from the browser's location bar), the user agent must use the following algorithm:
Let starting point be the currently focused area of a top-level traversable, if the user requested to move focus sequentially from there, or else the top-level traversable itself, if the user instead requested to move focus from outside the top-level traversable.
If there is a sequential focus navigation starting point defined and it is inside starting point, then let starting point be the sequential focus navigation starting point instead.
Let direction be "forward" if the
user requested the next control, and "backward" if the user requested the previous
control.
Loop: Let selection mechanism be "sequential" if starting point is a
navigable or if starting point is in its Document's
sequential focus navigation order.
Otherwise, starting point is not in its Document's sequential
focus navigation order; let selection mechanism be "DOM".
Let candidate be the result of running the sequential navigation search algorithm with starting point, direction, and selection mechanism.
If candidate is not null, then run the focusing steps for candidate and return.
Otherwise, unset the sequential focus navigation starting point.
If starting point is a top-level traversable, or a focusable area in the top-level traversable, the user agent should transfer focus to its own controls appropriately (if any), honouring direction, and then return.
If the user agent has no sequentially focusable controls — a kiosk-mode browser, for instance — then the user agent may instead restart these steps with the starting point being the top-level traversable itself.
Otherwise, starting point is a focusable area in a child navigable. Set starting point to that child navigable's parent and return to the step labeled loop.
Support in all current engines.
The blur() method, when
invoked, should run the unfocusing steps for the element on which the method was
called. User agents may selectively or uniformly ignore calls to this method for usability
reasons.
autofocus attributeWhen the autofocus attribute is specified on an element
inside dialog elements or HTML elements whose popover attribute is set, then it will be focused when the dialog or
popover becomes shown.
The autofocus attribute is a boolean
attribute.
There must not be two elements with the same nearest ancestor autofocus scoping root
element that both have the autofocus attribute
specified.
When an element with the autofocus attribute specified
is inserted into a document, run the
following steps:
If the user has indicated (for example, by starting to type in a form control) that they do not wish focus to be changed, then optionally return.
Let target be the element's node document.
If target is not fully active, then return.
If target's active sandboxing flag set has the sandboxed automatic features browsing context flag, then return.
For each ancestorNavigable of target's ancestor navigables: if ancestorNavigable's active document's origin is not same origin with target's origin, then return.
Let topDocument be target's node navigable's top-level traversable's active document.
If topDocument's autofocus processed flag is false, then remove the element from topDocument's autofocus candidates, and append the element to topDocument's autofocus candidates.
Support in one engine only.
The autofocus IDL attribute must reflect the
content attribute of the same name.
This section is non-normative.
Each element that can be activated or focused can be assigned a single key combination to
activate it, using the accesskey attribute.
The exact shortcut is determined by the user agent, based on information about the user's
keyboard, what keyboard shortcuts already exist on the platform, and what other shortcuts have
been specified on the page, using the information provided in the accesskey attribute as a guide.
In order to ensure that a relevant keyboard shortcut is available on a wide variety of input
devices, the author can provide a number of alternatives in the accesskey attribute.
Each alternative consists of a single character, such as a letter or digit.
User agents can provide users with a list of the keyboard shortcuts, but authors are encouraged
to do so also. The accessKeyLabel IDL attribute returns a
string representing the actual key combination assigned by the user agent.
accesskey
attributeSupport in all current engines.
All HTML elements may have the accesskey
content attribute set. The accesskey attribute's value is used
by the user agent as a guide for creating a keyboard shortcut that activates or focuses the
element.
If specified, the value must be an ordered set of unique space-separated tokens none of which are identical to another token and each of which must be exactly one code point in length.
Whenever an element's accesskey attribute is set, changed,
or removed, the user agent must update the element's assigned access key by running
the following steps:
If the element has no accesskey attribute, then skip
to the fallback step below.
Otherwise, split the attribute's value on ASCII whitespace, and let keys be the resulting tokens.
For each value in keys in turn, in the order the tokens appeared in the attribute's value, run the following substeps:
If the value is not a string exactly one code point in length, then skip the remainder of these steps for this value.
If the value does not correspond to a key on the system's keyboard, then skip the remainder of these steps for this value.
If the user agent can find a mix of zero or more modifier keys that, combined with the key that
corresponds to the value given in the attribute, can be used as the access key, then the user
agent may assign that combination of keys as the element's assigned access key and
return.
Fallback: Optionally, the user agent may assign a key combination of its choosing as the element's assigned access key and then return.
If this step is reached, the element has no assigned access key.
Once a user agent has selected and assigned an access key for an element, the user agent should
not change the element's assigned access key unless the accesskey content attribute is changed or the element is moved to
another Document.
When the user presses the key combination corresponding to the assigned access key for an element, if the element defines a command, the command's facet is false (visible), the command's Disabled State facet is also false (enabled), the element is in a document that has a non-null browsing context, and neither the element nor any of its ancestors has a attribute specified, then the user agent must trigger the Action of the command.
Support in all current engines.
The accessKey IDL
attribute must reflect the accesskey content
attribute.
The accessKeyLabel IDL attribute must return a string that
represents the element's assigned access key, if any. If the element does not have
one, then the IDL attribute must return the empty string.
contenteditable content attributeSupport in all current engines.
Global_attributes/contenteditable
Support in all current engines.
The contenteditable content attribute is an
enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
true
| true | The element is editable. |
| (the empty string) | ||
false
| false | The element is not editable. |
plaintext-only
| plaintext-only | Only the element's raw text content is editable; rich formatting is disabled. |
The isContentEditable IDL attribute, on getting, must
return true if the element is either an editing host or editable, and
false otherwise.
designMode getter and setterThe designMode setter steps are:
Let value be the given value, converted to ASCII lowercase.
If value is "on" and this's design mode
enabled is false, then:
Set this's design mode enabled to true.
Reset this's active range's start and end boundary points to be at the start of this.
Run the focusing steps for this's document element, if non-null.
If value is "off", then set this's
design mode enabled to false.
Authors are encouraged to set the 'white-space' property on editing hosts and on markup that was originally created through these editing mechanisms to the value 'pre-wrap'. Default HTML whitespace handling is not well suited to WYSIWYG editing, and line wrapping will not work correctly in some corner cases if 'white-space' is left at its default value.
The definition of the terms active range, editing host
of, and editable, the user
interface requirements of elements that are editing hosts or
editable, the
execCommand(),
queryCommandEnabled(),
queryCommandIndeterm(),
queryCommandState(),
queryCommandSupported(), and
queryCommandValue()
methods, text selections, and the delete the
selection algorithm are defined in execCommand. [EXECCOMMAND]
User agents can support the checking of spelling and grammar of editable text, either in form
controls (such as the value of textarea elements), or in elements in an editing
host (e.g. using contenteditable).
Support in all current engines.
The spellcheck
attribute is an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
true
| true | Spelling and grammar will be checked. |
| (the empty string) | ||
false
| false | Spelling and grammar will not be checked. |
The attribute's missing value default and invalid value default are both the default state. The default state indicates that the
element is to act according to a default behavior, possibly based on the parent element's own
spellcheck state, as defined below.
On setting, if the new value is true, then the element's spellcheck content attribute must be set to
"true", otherwise it must be set to "false".
User agents should only consider the following pieces of text as checkable for the purposes of this feature:
input elements whose type attributes are in the Text, Search,
URL, or Email states and that are mutable (i.e. that do not have the readonly attribute specified and that are not disabled).textarea elements that do not
have a readonly attribute and that are not disabled.Text nodes that are children of editing
hosts or editable elements.For text that is part of a Text node, the element with which the text is
associated is the element that is the immediate parent of the first character of the word,
sentence, or other piece of text. For text in attributes, it is the attribute's element. For the
values of input and textarea elements, it is the element itself.
To determine if a word, sentence, or other piece of text in an applicable element (as defined above) is to have spelling- and grammar-checking enabled, the UA must use the following algorithm:
spellcheck content attribute, then: if that attribute is in the
true state, then checking is enabled; otherwise, if that attribute is in the false
state, then checking is disabled.spellcheck content attribute that is not in the default
state, then: if the nearest such ancestor's spellcheck
content attribute is in the true state, then
checking is enabled; otherwise, checking is disabled.If the checking is enabled for a word/sentence/text, the user agent should indicate spelling
and grammar errors in that text. User agents should take into account the other semantics given in
the document when suggesting spelling and grammar corrections. User agents may use the language of
the element to determine what spelling and grammar rules to use, or may use the user's preferred
language settings. UAs should use input element attributes such as pattern to ensure that the resulting value is valid, where
possible.
If checking is disabled, the user agent should not indicate spelling or grammar errors for that text.
User agents offer writing suggestions as users type into editable regions, either in form
controls (e.g., the textarea element) or in elements in an editing host.
The writingsuggestions content attribute is an
enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
true
| true | Writing suggestions should be offered on this element. |
| (the empty string) | ||
false
| false | Writing suggestions should not be offered on this element. |
The attribute's invalid value default is the true state.
The writingSuggestions setter steps are:
Set this's writingsuggestions
content attribute to the given value.
User agents should only offer suggestions within an element's scope if the result of running the following algorithm given element returns true:
If the user has disabled writing suggestions, then return false.
If none of the following conditions are true:
element is an input element whose type attribute is in either the Text, Search, Telephone, URL,
or Email state and is mutable;
element is an editing host or is editable,
then return false.
If element has an inclusive ancestor with a writingsuggestions content attribute that's not in the
default and the nearest such
ancestor's writingsuggestions content attribute is
in the false state, then return
false.
Otherwise, return true.
Some methods of entering text, for example virtual keyboards on mobile devices, and also voice
input, often assist users by automatically capitalizing the first letter of sentences (when
composing text in a language with this convention). A virtual keyboard that implements
autocapitalization might automatically switch to showing uppercase letters (but allow the user to
toggle it back to lowercase) when a letter that should be autocapitalized is about to be typed.
Other types of input, for example voice input, may perform autocapitalization in a way that does
not give users an option to intervene first. The autocapitalize attribute allows authors to control such
behavior.
The autocapitalize attribute, as typically
implemented, does not affect behavior when typing on a physical keyboard. (For this reason, as
well as the ability for users to override the autocapitalization behavior in some cases or edit
the text after initial input, the attribute must not be relied on for any sort of input
validation.)
The autocapitalize attribute can be used on an editing host to control autocapitalization behavior for the hosted
editable region, on an input or textarea element to control the behavior
for inputting text into that element, or on a form element to control the default
behavior for all autocapitalize-and-autocorrect inheriting
elements associated with the form element.
The autocapitalize attribute never causes
autocapitalization to be enabled for input elements whose type attribute is in one of the URL, Email, or Password states. (This behavior is included
in the used autocapitalization hint algorithm
below.)
Global_attributes/autocapitalize
Support in all current engines.
The autocapitalize attribute is an enumerated
attribute whose states are the possible autocapitalization hints. The autocapitalization hint specified by the
attribute's state combines with other considerations to form the used autocapitalization
hint, which informs the behavior of the user agent. The keywords for this attribute and
their state mappings are as follows:
| Keyword | State |
|---|---|
off
| none |
on
| sentences |
words
| words |
characters
| characters |
The attribute's missing value default is the default state, and its invalid value default is the sentences state.
The autocapitalize setter steps are to set the autocapitalize content attribute to the given value.
User agents or input methods may choose to ignore or override the used autocapitalization hint in certain circumstances.
The used autocapitalization hint for an element element is computed using the following algorithm:
If element is an input element whose type attribute is in one of the URL, Email, or
Password states, then return default.
If element is an input element or a textarea element,
then return element's own autocapitalization hint.
If element is an editing host or an editable element, then return the own autocapitalization hint of the editing host of element.
Assert: this step is never reached, since text input only occurs in elements that meet one of the above criteria.
Some methods of entering text assist users by automatically correcting misspelled words while
typing, a process also known as autocorrection. User agents can support autocorrection of editable
text, either in form controls (such as the value of textarea elements), or in
elements in an editing host (e.g., using contenteditable). Autocorrection may be accompanied by user
interfaces indicating that text is about to be autocorrected or has been autocorrected, and is
commonly performed when inserting punctuation characters, spaces, or new paragraphs after
misspelled words. The autocorrect attribute allows authors
to control such behavior.
The autocorrect attribute can be used on an editing host
to control autocorrection behavior for the hosted editable region, on an input or
textarea element to control the behavior when inserting text into that element, or on
a form element to control the default behavior for all autocapitalize-and-autocorrect inheriting
elements associated with the form element.
The autocorrect attribute never causes autocorrection to
be enabled for input elements whose type
attribute is in one of the URL, E-mail, or Password states. (This behavior is included
in the used autocorrection state algorithm below.)
The autocorrect attribute is an enumerated attribute with the
following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
on
| on | The user agent is permitted to automatically correct spelling errors while the user types. Whether spelling is automatically corrected while typing left is for the user agent to decide, and may depend on the element as well as the user's preferences. |
| (the empty string) | ||
off
| off | The user agent is not allowed to automatically correct spelling while the user types. |
The attribute's invalid value default and missing value default are both the on state.
inputmode attributeUser agents can support the inputmode attribute on form
controls (such as the value of textarea elements), or in elements in an editing
host (e.g., using contenteditable).
Support in all current engines.
The inputmode
content attribute is an enumerated attribute that specifies what kind of input
mechanism would be most helpful for users entering content.
| Keyword | Description |
|---|---|
none
| The user agent should not display a virtual keyboard. This keyword is useful for content that renders its own keyboard control. |
text
| The user agent should display a virtual keyboard capable of text input in the user's locale. |
tel
| The user agent should display a virtual keyboard capable of telephone number input. This should including keys for the digits 0 to 9, the "#" character, and the "*" character. In some locales, this can also include alphabetic mnemonic labels (e.g., in the US, the key labeled "2" is historically also labeled with the letters A, B, and C). |
url
| The user agent should display a virtual keyboard capable of text input in the user's locale, with keys for aiding in the input of URLs, such as that for the "/" and "." characters and for quick input of strings commonly found in domain names such as "www." or ".com". |
email
| The user agent should display a virtual keyboard capable of text input in the user's locale, with keys for aiding in the input of email addresses, such as that for the "@" character and the "." character. |
numeric
| The user agent should display a virtual keyboard capable of numeric input. This keyword is useful for PIN entry. |
decimal
| The user agent should display a virtual keyboard capable of fractional numeric input. Numeric keys and the format separator for the locale should be shown. |
search
| The user agent should display a virtual keyboard optimized for search. |
Support in all current engines.
When inputmode is unspecified (or is in a state not
supported by the user agent), the user agent should determine the default virtual keyboard to be
shown. Contextual information such as the input type or
pattern attributes should be used to determine which type
of virtual keyboard should be presented to the user.
enterkeyhint
attributeUser agents can support the enterkeyhint
attribute on form controls (such as the value of textarea elements), or in elements
in an editing host (e.g., using contenteditable).
Global_attributes/enterkeyhint
Support in all current engines.
The enterkeyhint content attribute is an enumerated
attribute that specifies what action label (or icon) to present for the enter key on
virtual keyboards. This allows authors to customize the presentation of the enter key in order to
make it more helpful for users.
| Keyword | Description |
|---|---|
enter
| The user agent should present a cue for the operation 'enter', typically inserting a new line. |
done
| The user agent should present a cue for the operation 'done', typically meaning there is nothing more to input and the input method editor (IME) will be closed. |
go
| The user agent should present a cue for the operation 'go', typically meaning to take the user to the target of the text they typed. |
next
| The user agent should present a cue for the operation 'next', typically taking the user to the next field that will accept text. |
previous
| The user agent should present a cue for the operation 'previous', typically taking the user to the previous field that will accept text. |
search
| The user agent should present a cue for the operation 'search', typically taking the user to the results of searching for the text they have typed. |
send
| The user agent should present a cue for the operation 'send', typically delivering the text to its target. |
Support in all current engines.
When enterkeyhint is unspecified (or is in a state not
supported by the user agent), the user agent should determine the default action label (or icon)
to present. Contextual information such as the inputmode,
type, or pattern
attributes should be used to determine which action label (or icon) to present on the virtual
keyboard.
One of the matches is identified to the user as the active match. It is highlighted and scrolled into view. The user can navigate through the matches by advancing the active match using the find-in-page interface.
When find-in-page begins searching for matches, all elements in the page which do not have their attribute set should have the of their second slot become accessible, without modifying the attribute, in order to make find-in-page able to search through it. Similarly, all HTML elements with the attribute in the state should have their become accessible without modifying the attribute in order to make find-in-page able to search through them. After find-in-page finishes searching for matches, the elements and the elements with the attribute in the state should have their contents become skipped again. This entire process must happen synchronously (and so is not observable to users or to author code). [CSSCONTAIN]
When find-in-page chooses a new , perform the following steps:
Let node be the first node in the .
on the given node's to run the following steps:
Run the on node.
Run the on node.
The find-in-page process is invoked in the context of a document, and may have an effect on the selection of that document. Specifically, the range that defines the active match can dictate the current selection. These selection updates, however, can happen at different times during the find-in-page process (e.g. upon the find-in-page interface dismissal or upon a change in the active match range).
On platforms where pressing the Esc key is interpreted as a close
request, the user agent must interpret the key being pressed down as the close
request, instead of the key being released. Thus, in the above algorithm, the "relevant events"
that are fired must be the single keydown event.
Most of the complexity of the close watcher manager comes from anti-abuse protections designed to prevent developers from disabling users' history traversal abilities, for platforms where a close request's fallback action is the main mechanism of history traversal. In particular:
The grouping of close watchers is designed so that if multiple close watchers are created without history-action activation, they are grouped together, so that a user-triggered close request will close all of the close watchers in a group. This ensures that web developers can't intercept an unlimited number of close requests by creating close watchers; instead they can create a number equal to at most 1 + the number of times the user activates the page.
The next user interaction allows a new group boolean encourages web developers to create close watchers in a way that is tied to individual user activations. Without it, each user activation would increase the allowed number of groups, even if the web developer isn't "using" those user activations to create close watchers. In short:
Allowed: user interaction; create a close watcher in its own group; user interaction; create a close watcher in a second independent group.
Disallowed: user interaction; user interaction; create a close watcher in its own group; create a close watcher in a second independent group.
Allowed: user interaction; user interaction; create a close watcher in its own group; create a close watcher grouped with the previous one.
This protection is not important for upholding our desired invariant of creating at most (1 + the number of times the user activates the page) groups. A determined abuser will just create one close watcher per user interaction, "banking" them for future abuse. But this system causes more predictable behavior for the normal case, and encourages non-abusive developers to create close watchers directly in response to user interactions.
A close watcher closeWatcher is active if closeWatcher's window's close watcher manager contains any list which contains closeWatcher.
To establish a close watcher given a Window window, a list
of steps cancelAction, a
list of steps closeAction,
and an algorithm that returns a boolean getEnabledState:
Assert: window's associated Document is fully
active.
Let closeWatcher be a new close watcher, with
Let manager be window's close watcher manager.
If manager's groups's size is less than manager's allowed number of groups, then append « closeWatcher » to manager's groups.
Otherwise:
Set manager's next user interaction allows a new group to true.
Return closeWatcher.
CloseWatcher interfaceThe following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the
CloseWatcher interface:
| Event handler | Event handler event type |
|---|---|
oncancel | cancel
|
onclose | close
|
Combined, the above two examples show how requestClose() and close() differ. Because we used requestClose() in the click event handler for the close button, clicking that button will
trigger the CloseWatcher's cancel event, and thus
potentially ask the user for confirmation if there is unsaved data. If we had used close(), then this check would be skipped. Sometimes that
is appropriate, but usually requestClose() is
the better option for user-triggered close requests.
Support in all current engines.
This section defines an event-based drag-and-drop mechanism.
This specification does not define exactly what a drag-and-drop operation actually is.
On a visual medium with a pointing device, a drag operation could be the default action of a
mousedown event that is followed by a series of mousemove events, and the drop could be triggered by the mouse
being released.
When using an input modality other than a pointing device, users would probably have to explicitly indicate their intention to perform a drag-and-drop operation, stating what they wish to drag and where they wish to drop it, respectively.
However it is implemented, drag-and-drop operations must have a starting point (e.g. where the mouse was clicked, or the start of the selection or element that was selected for the drag), may have any number of intermediate steps (elements that the mouse moves over during a drag, or elements that the user picks as possible drop points as they cycle through possibilities), and must either have an end point (the element above which the mouse button was released, or the element that was finally selected), or be canceled. The end point must be the last element selected as a possible drop point before the drop occurs (so if the operation is not canceled, there must be at least one element in the middle step).
This section is non-normative.
To make an element draggable, give the element a draggable
attribute, and set an event listener for dragstart that
stores the data being dragged.
The event handler typically needs to check that it's not a text selection that is being
dragged, and then needs to store data into the DataTransfer object and set the
allowed effects (copy, move, link, or some combination).
For example:
To accept a drop, the drop target has to listen to the following events:
dragenter event handler reports
whether or not the drop target is potentially willing to accept the drop, by canceling the
event.dragover event handler specifies what feedback
will be shown to the user, by setting the dropEffect attribute of the
DataTransfer associated with the event. This event also needs to be canceled.drop event handler has a final chance to accept or
reject the drop. If the drop is accepted, the event handler must perform the drop operation on
the target. This event needs to be canceled, so that the dropEffect attribute's value can be used by the
source. Otherwise, the drop operation is rejected.For example:
To remove the original element (the one that was dragged) from the display, the dragend event can be used.
For our example here, that means updating the original markup to handle that event:
When a drag data store is created, it
must be initialized such that its drag data store item list is empty, it has no
drag data store default feedback, it has no drag data store bitmap and
drag data store hot spot coordinate, its drag data store mode is protected mode, and its drag data store allowed effects
state is the string "uninitialized".
DataTransfer interfaceSupport in all current engines.
DataTransfer objects are used to expose the drag data store that
underlies a drag-and-drop operation.
DataTransfer objects that are created as part of drag-and-drop events are only valid while those events are being fired.
A DataTransfer object is associated with a drag data store while it
is valid.
The dropEffect attribute controls the drag-and-drop
feedback that the user is given during a drag-and-drop operation. When the
DataTransfer object is created, the dropEffect attribute is set to a string value. On
getting, it must return its current value. On setting, if the new value is one of "none", "copy", "link", or "move", then the attribute's current value
must be set to the new value. Other values must be ignored.
The effectAllowed attribute is used in the
drag-and-drop processing model to initialize the dropEffect attribute during the dragenter and dragover events. When the DataTransfer object is
created, the effectAllowed attribute is set
to a string value. On getting, it must return its current value. On setting, if drag data
store's mode is the read/write mode and the new value is one of "none", "copy", "copyLink", "copyMove", "link", "linkMove", "move", "all", or "uninitialized", then the attribute's
current value must be set to the new value. Otherwise, it must be left unchanged.
DataTransferItemList interfaceSupport in all current engines.
Each DataTransfer object is associated with a DataTransferItemList
object.
While the DataTransferItemList object's DataTransfer object is
associated with a drag data store, the DataTransferItemList object's
mode is the same as the drag data store mode. When the
DataTransferItemList object's DataTransfer object is not
associated with a drag data store, the DataTransferItemList object's
mode is the disabled mode. The drag data store referenced in this
section (which is used only when the DataTransferItemList object is not in the
disabled mode) is the drag data store with which the
DataTransferItemList object's DataTransfer object is associated.
When a DataTransferItemList object is not in the disabled mode, its
supported property indices are the indices of the drag data store
item list.
To determine the value of an indexed property
i of a DataTransferItemList object, the user agent must return a
DataTransferItem object representing the ith item in the
drag data store. The same object must be returned each time a particular item is
obtained from this DataTransferItemList object. The DataTransferItem
object must be associated with the same DataTransfer object as the
DataTransferItemList object when it is first created.
The clear() method, if the
DataTransferItemList object is in the read/write mode,
must remove all the items from the drag data store. Otherwise, it must do
nothing.
DataTransferItem interfaceSupport in all current engines.
Each DataTransferItem object is associated with a DataTransfer
object.
While the DataTransferItem object's DataTransfer object is associated
with a drag data store and that drag data store's drag data store
item list still contains the item that the DataTransferItem object represents,
the DataTransferItem object's mode is the same as the drag data store
mode. When the DataTransferItem object's DataTransfer object is
not associated with a drag data store, or if the item that the
DataTransferItem object represents has been removed from the relevant drag data
store item list, the DataTransferItem object's mode is the disabled
mode. The drag data store referenced in this section (which is used only when the
DataTransferItem object is not in the disabled mode) is the drag data
store with which the DataTransferItem object's DataTransfer
object is associated.
The kind attribute must return the empty string if the
DataTransferItem object is in the disabled mode; otherwise it must return the
string given in the cell from the second column of the following table from the row whose cell in
the first column contains the drag data item kind of the item represented by the
DataTransferItem object:
| Kind | String |
|---|---|
| Text | "string"
|
| File | "file"
|
DragEvent interfaceSupport in all current engines.
Support in all current engines.
The drag-and-drop processing model involves several events. They all use the
DragEvent interface.
When the user attempts to begin a drag operation, the user agent must run the following steps. User agents must act as if these steps were run even if the drag actually started in another document or application and the user agent was not aware that the drag was occurring until it intersected with a document under the user agent's purview.
Determine what is being dragged, as follows:
If the drag operation was invoked on a selection, then it is the selection that is being dragged.
Otherwise, if the drag operation was invoked on a Document, it is the first
element, going up the ancestor chain, starting at the node that the user tried to drag, that has
the IDL attribute draggable set to true. If there is no such
element, then nothing is being dragged; return, the drag-and-drop operation is never
started.
Otherwise, the drag operation was invoked outside the user agent's purview. What is being dragged is defined by the document or application where the drag was started.
Create a drag data store. All the DND events fired subsequently by the steps in this section must use this drag data store.
If it is a selection that is being dragged, then the source node is the
Text node that the user started the drag on (typically the Text node
that the user originally clicked). If the user did not specify a particular node, for example if
the user just told the user agent to begin a drag of "the selection", then the source
node is the first Text node containing a part of the selection.
Otherwise, if it is an element that is being dragged, then the source node is the element that is being dragged.
Otherwise, the source node is part of another document or application. When this specification requires that an event be dispatched at the source node in this case, the user agent must instead follow the platform-specific conventions relevant to that situation.
If it is a selection that is being dragged, then the list of dragged nodes contains, in tree order, every node that is partially or completely included in the selection (including all their ancestors).
Otherwise, the list of dragged nodes contains only the source node, if any.
If it is a selection that is being dragged, then add an item to the drag data store item list, with its properties set as follows:
text/plain"Otherwise, if any files are being dragged, then add one item per file to the drag data store item list, with their properties set as follows:
application/octet-stream" otherwise.If the drag initiated outside of the application, the user agent must add items to the drag data store item list as appropriate for the data being dragged, honoring platform conventions where appropriate; however, if the platform conventions do not use MIME types to label dragged data, the user agent must make a best-effort attempt to map the types to MIME types, and, in any case, all the drag data item type strings must be converted to ASCII lowercase.
User agents may also add one or more items representing the selection or dragged element(s) in other forms, e.g. as HTML.
If the list of dragged nodes is not empty, then extract the microdata from those nodes into a JSON form, and add one item to the drag data store item list, with its properties set as follows:
application/microdata+jsonRun the following substeps:
Let urls be « ».
For each node in the list of dragged nodes:
a element with an href attributehref content attribute's value,
relative to the element's node document.img element with a src
attributesrc content attribute's value, relative to
the element's node document.If urls is still empty, then return.
Let url string be the result of concatenating the strings in urls, in the order they were added, separated by a U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF).
Add one item to the drag data store item list, with its properties set as follows:
text/uri-listUpdate the drag data store default feedback as appropriate for the user agent (if the user is dragging the selection, then the selection would likely be the basis for this feedback; if the user is dragging an element, then that element's rendering would be used; if the drag began outside the user agent, then the platform conventions for determining the drag feedback should be used).
Fire a DND event named dragstart at the
source node.
If the event is canceled, then the drag-and-drop operation should not occur; return.
Fire a pointer event at the source node named pointercancel, and fire any other follow-up events as
required by Pointer Events. [POINTEREVENTS]
Initiate the drag-and-drop operation in a manner consistent with platform conventions, and as described below.
The drag-and-drop feedback must be generated from the first of the following sources that is available:
During the drag operation, the element directly indicated by the user as the drop target is called the immediate user selection. (Only elements can be selected by the user; other nodes must not be made available as drop targets.) However, the immediate user selection is not necessarily the current target element, which is the element currently selected for the drop part of the drag-and-drop operation.
The immediate user selection changes as the user selects different elements (either by pointing at them with a pointing device, or by selecting them in some other way). The current target element changes when the immediate user selection changes, based on the results of event listeners in the document, as described below.
Both the current target element and the immediate user selection can be null, which means no target element is selected. They can also both be elements in other (DOM-based) documents, or other (non-web) programs altogether. (For example, a user could drag text to a word-processor.) The current target element is initially null.
User agents must, as soon as the drag operation is initiated and every 350ms (±200ms) thereafter for as long as the drag operation is ongoing, queue a task to perform the following steps in sequence:
If the user agent is still performing the previous iteration of the sequence (if any) when the next iteration becomes due, return for this iteration (effectively "skipping missed frames" of the drag-and-drop operation).
Fire a DND event named drag at the
source node. If this event is canceled, the user agent must set the current
drag operation to "none" (no
drag operation).
If the drag event was not canceled and the user has not
ended the drag-and-drop operation, check the state of the drag-and-drop operation, as
follows:
If the user is indicating a different immediate user selection than during the last iteration (or if this is the first iteration), and if this immediate user selection is not the same as the current target element, then update the current target element as follows:
Set the current target element to null also.
Set the current target element to the immediate user selection.
Fire a DND event named dragenter
at the immediate user selection.
If the event is canceled, then set the current target element to the immediate user selection.
Otherwise, run the appropriate step from the following list:
textarea, or an input element whose type attribute is in the Text state) or an editing host or
editable element, and the drag data store item list has an item
with the drag data item type string "text/plain" and the
drag data item kind textSet the current target element to the immediate user selection anyway.
Leave the current target element unchanged.
Fire a DND event named dragenter
at the body element, if there is one, or at the Document object,
if not. Then, set the current target element to the body
element, regardless of whether that event was canceled or not.
If the previous step caused the current target element to change, and if the
previous target element was not null or a part of a non-DOM document, then fire a DND
event named dragleave at the previous target
element, with the new current target element as the specific related
target.
If the current target element is a DOM element, then fire a DND
event named dragover at this current
target element.
If the dragover event is not canceled, run the
appropriate step from the following list:
textarea, or an input element whose type attribute is in the Text state) or an editing host or
editable element, and the drag data store item list has an item
with the drag data item type string "text/plain" and the drag
data item kind textSet the current drag operation to either "copy" or "move", as appropriate given the platform
conventions.
Reset the current drag operation to "none".
Otherwise (if the dragover event is
canceled), set the current drag operation based on the values of the effectAllowed and dropEffect attributes of the
DragEvent object's dataTransfer
object as they stood after the event dispatch
finished, as per the following table:
effectAllowed | dropEffect | Drag operation |
|---|---|---|
"uninitialized", "copy", "copyLink", "copyMove", or "all" | "copy" | "copy" |
"uninitialized", "link", "copyLink", "linkMove", or "all" | "link" | "link" |
"uninitialized", "move", "copyMove", "linkMove", or "all" | "move" | "move" |
| Any other case | "none" | |
Otherwise, if the current target element is not a DOM element, use platform-specific mechanisms to determine what drag operation is being performed (none, copy, link, or move), and set the current drag operation accordingly.
Update the drag feedback (e.g. the mouse cursor) to match the current drag operation, as follows:
| Drag operation | Feedback |
|---|---|
"copy" | Data will be copied if dropped here. |
"link" | Data will be linked if dropped here. |
"move" | Data will be moved if dropped here. |
"none" | No operation allowed, dropping here will cancel the drag-and-drop operation. |
Otherwise, if the user ended the drag-and-drop operation (e.g. by releasing the mouse button
in a mouse-driven drag-and-drop interface), or if the drag
event was canceled, then this will be the last iteration. Run the following steps, then stop the
drag-and-drop operation:
If the current drag operation is "none" (no drag operation), or, if the user
ended the drag-and-drop operation by canceling it (e.g. by hitting the Escape key),
or if the current target element is null, then the drag operation failed. Run
these substeps:
Let dropped be false.
If the current target element is a DOM element, fire a DND
event named dragleave at it; otherwise, if
it is not null, use platform-specific conventions for drag cancelation.
Set the current drag operation to "none".
Otherwise, the drag operation might be a success; run these substeps:
Let dropped be true.
If the current target element is a DOM element, fire a DND
event named drop at it; otherwise, use
platform-specific conventions for indicating a drop.
If the event is canceled, set the current drag operation to the value of the
dropEffect attribute of the
DragEvent object's dataTransfer
object as it stood after the event dispatch
finished.
Otherwise, the event is not canceled; perform the event's default action, which depends on the exact target as follows:
textarea, or an input element whose type attribute is in the Text state) or an editing host or
editable element, and the drag data store item list has an item
with the drag data item type string "text/plain" and the
drag data item kind textInsert the actual data of the first item in the drag data store item
list to have a drag data item type
string of "text/plain" and a drag
data item kind that is text into the text control or
editing host or editable element in a manner consistent with
platform-specific conventions (e.g. inserting it at the current mouse cursor position, or
inserting it at the end of the field).
Reset the current drag operation to "none".
Fire a DND event named dragend at the
source node.
Run the appropriate steps from the following list as the default action of the dragend event:
move", and the source of the
drag-and-drop operation is a selection in the DOM that is entirely contained within an
editing hostmove", and the source of the
drag-and-drop operation is a selection in a text controlThe user agent should delete the dragged selection from the relevant text control.
none"The drag was canceled. If the platform conventions dictate that this be represented to the user (e.g. by animating the dragged selection going back to the source of the drag-and-drop operation), then do so.
The event has no default action.
For the purposes of this step, a text control is a textarea element or
an input element whose type attribute is in
one of the
Text,
Search,
Tel,
URL,
Email,
Password, or
Number
states.
This section is non-normative.
The following events are involved in the drag-and-drop model.
| Event name | Target | Cancelable? | Drag data store mode | dropEffect | Default Action |
|---|---|---|---|---|---|
dragstartSupport in all current engines. Firefox9+Safari3.1+Chrome1+ Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Source node | ✓ Cancelable | Read/write mode | "none" | Initiate the drag-and-drop operation |
dragSupport in all current engines. Firefox9+Safari3.1+Chrome1+ Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Source node | ✓ Cancelable | Protected mode | "none" | Continue the drag-and-drop operation |
dragenterSupport in all current engines. Firefox9+Safari3.1+Chrome1+ Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Immediate user selection or the body element | ✓ Cancelable | Protected mode | Based on effectAllowed value | Reject immediate user selection as potential target element |
dragleaveSupport in all current engines. Firefox9+Safari3.1+Chrome1+ Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Previous target element | — | Protected mode | "none" | None |
dragoverSupport in all current engines. Firefox9+Safari3.1+Chrome1+ Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Current target element | ✓ Cancelable | Protected mode | Based on effectAllowed value | Reset the current drag operation to "none" |
dropSupport in all current engines. Firefox9+Safari3.1+Chrome1+ Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Current target element | ✓ Cancelable | Read-only mode | Current drag operation | Varies |
dragendSupport in all current engines. Firefox9+Safari3.1+Chrome1+ Opera12+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Source node | — | Protected mode | Current drag operation | Varies |
All of these events bubble, are composed, and the effectAllowed attribute always has the value it had
after the dragstart event, defaulting to "uninitialized" in the dragstart event.
draggable attributeSupport in all current engines.
All HTML elements may have the draggable content attribute set. The draggable attribute is an enumerated attribute with
the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
true
| true | The element will be draggable. |
false
| false | The element will not be draggable. |
An element with a draggable attribute should also have a
title attribute that names the element for the purpose of
non-visual interactions.
If an element's draggable content attribute has the state
true, the draggable IDL attribute must return true.
Otherwise, if the element's draggable content attribute
has the state false, the draggable IDL attribute must return false.
Otherwise, the element's draggable content attribute has
the state auto. If the element is an
img element, an object element that represents an image, or
an a element with an href content
attribute, the draggable IDL attribute must return true;
otherwise, the draggable IDL attribute must return false.
If the draggable IDL attribute is set to the value false,
the draggable content attribute must be set to the literal
value "false". If the draggable IDL
attribute is set to the value true, the draggable content
attribute must be set to the literal value "true".
User agents must not make the data added to the DataTransfer object during the
dragstart event available to scripts until the drop event, because otherwise, if a user were to drag sensitive
information from one document to a second document, crossing a hostile third document in the
process, the hostile document could intercept the data.
For the same reason, user agents must consider a drop to be successful only if the user
specifically ended the drag operation — if any scripts end the drag operation, it must be
considered unsuccessful (canceled) and the drop event must not be
fired.
User agents should take care to not start drag-and-drop operations in response to script actions. For example, in a mouse-and-window environment, if a script moves a window while the user has their mouse button depressed, the UA would not consider that to start a drag. This is important because otherwise UAs could cause data to be dragged from sensitive sources and dropped into hostile documents without the user's consent.
User agents should filter potentially active (scripted) content (e.g. HTML) when it is dragged and when it is dropped, using a safelist of known-safe features. Similarly, relative URLs should be turned into absolute URLs to avoid references changing in unexpected ways. This specification does not specify how this is performed.
popover attributeSupport in all current engines.
When using popover on elements without accessibility
semantics, for instance the div element, authors should use the appropriate ARIA
attributes to ensure the popover is accessible.
The popover attribute is an enumerated
attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
auto
| auto | Closes other popovers when opened; has light dismiss and responds to close requests. |
| (the empty string) | ||
manual
| manual | Does not close other popovers; does not light dismiss or respond to close requests. |
hint | hint | Closes other hint popovers when opened, but not other auto popovers; has light dismiss and responds to close requests. |
The attribute's missing value default is the no popover state, and its invalid value default is the manual state.
Support in all current engines.
The following attribute change steps, given element, localName, oldValue, value, and namespace, are used for all HTML elements:
If namespace is not null, then return.
If localName is not popover, then
return.
If element's popover visibility state is in the showing state and oldValue and value are in different states, then run the hide popover algorithm given element, true, true, and false.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Buttons may have the following content attributes:
If specified, the popovertarget attribute value must
be the ID of an element with a popover attribute in the same tree as the button with the popovertarget attribute.
The popovertargetaction attribute is an
enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
toggle
| toggle | Shows or hides the targeted popover element. |
show
| show | Shows the targeted popover element. |
hide
| hide | Hides the targeted popover element. |
The attribute's missing value default and invalid value default are both the toggle state.
DOM interface:HTMLButtonElement/popoverTargetElement
Support in all current engines.
HTMLInputElement/popoverTargetElement
Support in all current engines.
The popoverTargetElement IDL attribute must
reflect the popovertarget attribute.
HTMLButtonElement/popoverTargetAction
Support in all current engines.
HTMLInputElement/popoverTargetAction
Support in all current engines.
This section describes features that apply most directly to web browsers. Having said that, except where specified otherwise, the requirements defined in this section do apply to all user agents, whether they are web browsers or not.
Origins are the fundamental currency of the web's security model. Two actors in the web platform that share an origin are assumed to trust each other and to have the same authority. Actors with differing origins are considered potentially hostile versus each other, and are isolated from each other to varying degrees.
Avoid using the document.domain setter. It
undermines the security protections provided by the same-origin policy. This is especially acute
when using shared hosting; for example, if an untrusted third party is able to host an HTTP
server at the same IP address but on a different port, then the same-origin protection that
normally protects two different sites on the same host will fail, as the ports are ignored when
comparing origins after the document.domain setter has
been used.
Because of these security pitfalls, this feature is in the process of being removed from the web platform. (This is a long process that takes many years.)
Instead, use postMessage() or
MessageChannel objects to communicate across origins in a safe manner.
The domain setter steps are:
If this's browsing context is
null, then throw a "SecurityError" DOMException.
If this's active sandboxing flag set has its sandboxed
document.domain browsing context flag set, then
throw a "SecurityError" DOMException.
Let effectiveDomain be this's origin's effective domain.
If effectiveDomain is null, then throw a
"SecurityError" DOMException.
If the given value is not
a registrable domain suffix of and is not equal to effectiveDomain, then throw
a "SecurityError" DOMException.
If the surrounding agent's agent cluster's is origin-keyed is true, then return.
Set this's origin's domain to the result of parsing the given value.
Per the processing model in the create
and initialize a new Document object, values
that are not the structured header boolean
true value (i.e., `?1`) will be ignored.
The consequences of using this header are that the resulting
Document's agent cluster key is its origin, instead of the corresponding site. In terms of observable effects, this means that
attempting to relax the same-origin
restriction using document.domain will instead do
nothing, and it will not be possible to send WebAssembly.Module objects to
cross-origin Documents (even if they are same site). Behind the scenes,
this isolation can allow user agents to allocate implementation-specific resources corresponding
to agent clusters, such as processes or threads, more
efficiently.
Note that within a browsing context group, the
`Origin-Agent-Cluster` header can never cause same-origin Document
objects to end up in different agent clusters, even if one
sends the header and the other doesn't. This is prevented by means of the
historical agent cluster key map.
The originAgentCluster getter steps are to return the
surrounding agent's agent cluster's is origin-keyed.
Headers/Cross-Origin-Opener-Policy
Support in all current engines.
The valid token values are the opener policy values. The token may also have
attached parameters; of these, the "report-to" parameter can have a valid URL
string identifying an appropriate reporting endpoint. [REPORTING]
Headers/Cross-Origin-Embedder-Policy
Support in all current engines.
The "coep" report type is a report type whose value
is "coep". It is visible to
ReportingObservers.
The valid token values are the embedder policy values. The token may also have attached parameters; of these, the "report-to" parameter can have a valid URL
string identifying an appropriate reporting endpoint. [REPORTING]
Window,
WindowProxy, and Location objectsAlthough typically objects cannot be accessed across origins, the web platform would not be true to itself if it did not have some legacy exceptions to that rule that the web depends upon.
This section uses the terminology and typographic conventions from the JavaScript specification. [JAVASCRIPT]
When perform a security check is invoked, with a platformObject, identifier, and type, run these steps:
If platformObject is not a Window or Location object,
then return.
For each e of CrossOriginProperties(platformObject):
If SameValue(e.[[Property]], identifier) is true, then:
If type is "method" and e has neither
[[NeedsGet]] nor [[NeedsSet]], then return.
Otherwise, if type is "getter" and
e.[[NeedsGet]] is true, then return.
Otherwise, if type is "setter" and
e.[[NeedsSet]] is true, then return.
If IsPlatformObjectSameOrigin(platformObject) is false, then
throw a "SecurityError" DOMException.
The [[CrossOriginPropertyDescriptorMap]] internal slot contains a map
with entries whose keys are (currentGlobal, objectGlobal,
propertyKey)-tuples and values are property descriptors, as a memoization of what is
visible to scripts when currentGlobal inspects a Window or
Location object from objectGlobal. It is filled lazily by
CrossOriginGetOwnPropertyHelper, which consults it on future lookups.
User agents should allow a value held in the map to be garbage collected along with its corresponding key when nothing holds a reference to any part of the value. That is, as long as garbage collection is not observable.
User agents may have an optimization whereby they remove key-value pairs from the map when
document.domain is set. This is not observable as document.domain cannot revisit an earlier value.
A JavaScript property name P is a cross-origin accessible window property
name if it is "window", "self", "location", "close", "closed",
"focus", "blur", "frames",
"length", "top", "opener",
"parent", "postMessage", or an array index
property name.
Window objectSupport in all current engines.
Support in all current engines.
For historical reasons, Window objects must also have a writable, configurable,
non-enumerable property named HTMLDocument whose value is the
Document interface object.
The open(url, target,
features) method steps are to run the window open steps with
url, target, and features.
The name setter steps are:
Set this's navigable's active session history entry's document state's navigable target name to the given value.
Window objectThe length getter steps are
to return this's associated
Document's document-tree child navigables's size.
Window objectThe Window object supports named
properties. The supported property names of a Window object
window at any moment consist of the following, in tree order according to
the element that contributed them, ignoring later duplicates:
window's document-tree child navigable target name property set;
the value of the name content attribute for all embed,
form, img, and object elements that
have a non-empty name content attribute and are in a document
tree with window's associated
Document as their root; and
the value of the id content attribute for all HTML
elements that have a non-empty id content attribute and are
in a document tree with window's associated Document as their
root.
To determine the value of a named property
name in a Window object window, the user agent must return the
value obtained using the following steps:
Let objects be the list of named objects of window with the name name.
If objects contains a navigable, then:
Let container be the first navigable container in
window's associated
Document's descendants whose
content navigable is in objects.
Return container's content navigable's active WindowProxy.
Otherwise, if objects has only one element, return that element.
Otherwise, return an HTMLCollection rooted at window's associated Document, whose filter matches
only named objects of window with
the name name. (By definition, these will all be elements.)
The opener setter steps are:
If the given value is null and this's browsing context is non-null, then set this's browsing context's opener browsing context to null.
If the given value is non-null, then perform ?
DefinePropertyOrThrow(this, "opener", {
[[Value]]: the given value, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true
}).
For historical reasons, the Window interface had some properties that represented
the visibility of certain web browser interface elements.
For privacy and interoperability reasons, those properties now return values that
represent whether the Window's browsing context's
is popup property is true or false.
Each interface element is represented by a BarProp object:
Support in all current engines.
Support in all current engines.
The following BarProp objects must exist for each Window object:
BarProp objectBarProp objectBarProp objectBarProp objectBarProp objectBarProp objectThe toolbar
attribute must return the toolbar BarProp object.
For historical reasons, the status attribute on the Window object must,
on getting, return the last string it was set to, and on setting, must set itself to the new
value. When the Window object is created, the attribute must be set to the empty
string. It does not do anything else.
Window objectsWindowProxy exotic objectThe WindowProxy exotic object must use the ordinary internal methods except where
it is explicitly specified otherwise below.
There is no WindowProxy interface object.
Every WindowProxy object has a [[Window]] internal slot representing the wrapped Window object.
Let W be the value of the [[Window]] internal slot of this.
If IsPlatformObjectSameOrigin(W) is true, then return ! OrdinaryGetPrototypeOf(W).
Return null.
Return ! SetImmutablePrototype(this, V).
Return true.
Return false.
Let W be the value of the [[Window]] internal slot of this.
If P is an array index property name, then:
Let index be ! ToUint32(P).
Let children be the document-tree child navigables of
W's associated
Document.
Let value be undefined.
If index is less than children's size, then:
Sort children in ascending order, with
navigableA being less than navigableB if navigableA's container was inserted into W's associated Document earlier than
navigableB's container was.
Set value to children[index]'s active WindowProxy.
If value is undefined, then:
If IsPlatformObjectSameOrigin(W) is true, then return undefined.
Throw a "SecurityError" DOMException.
Return PropertyDescriptor{ [[Value]]: value, [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: true }.
If IsPlatformObjectSameOrigin(W) is true, then return ! OrdinaryGetOwnProperty(W, P).
Let property be CrossOriginGetOwnPropertyHelper(W, P).
If property is not undefined, then return property.
If property is undefined and P is in W's document-tree child navigable target name property set, then:
Let value be the active
WindowProxy of the named
object of W with the name P.
Return PropertyDescriptor{ [[Value]]: value, [[Enumerable]]: false, [[Writable]]: false, [[Configurable]]: true }.
Return ? CrossOriginPropertyFallback(P).
Let W be the value of the [[Window]] internal slot of this.
If IsPlatformObjectSameOrigin(W) is true, then:
If P is an array index property name, return false.
Return ? OrdinaryDefineOwnProperty(W, P, Desc).
Throw a "SecurityError" DOMException.
Let W be the value of the [[Window]] internal slot of this.
Check if an access between two browsing contexts should be reported, given the current global object's browsing context, W's browsing context, P, and the current settings object.
If IsPlatformObjectSameOrigin(W) is true, then return ? OrdinaryGet(this, P, Receiver).
Return ? CrossOriginGet(this, P, Receiver).
Let W be the value of the [[Window]] internal slot of this.
Check if an access between two browsing contexts should be reported, given the current global object's browsing context, W's browsing context, P, and the current settings object.
If IsPlatformObjectSameOrigin(W) is true, then:
If P is an array index property name, then return false.
Return ? OrdinarySet(W, P, V, Receiver).
Return ? CrossOriginSet(this, P, V, Receiver).
Let W be the value of the [[Window]] internal slot of this.
If IsPlatformObjectSameOrigin(W) is true, then:
If P is an array index property name, then:
Let desc be ! this.[[GetOwnProperty]](P).
If desc is undefined, then return true.
Return false.
Return ? OrdinaryDelete(W, P).
Throw a "SecurityError" DOMException.
Let W be the value of the [[Window]] internal slot of this.
Let maxProperties be W's associated Document's document-tree
child navigables's size.
Let keys be the range 0 to maxProperties, exclusive.
If IsPlatformObjectSameOrigin(W) is true, then return the concatenation of keys and OrdinaryOwnPropertyKeys(W).
Return the concatenation of keys and ! CrossOriginOwnPropertyKeys(W).
Location interfaceSupport in all current engines.
Support in all current engines.
Support in all current engines.
Each Window object is associated with a unique instance of a Location
object, allocated when the Window object is created.
To create a Location object, run these steps:
Let location be a new Location platform
object.
Let valueOf be location's relevant realm.[[Intrinsics]].[[%Object.prototype.valueOf%]].
Perform ! location.[[DefineOwnProperty]]("valueOf", {
[[Value]]: valueOf,
[[Writable]]: false,
[[Enumerable]]: false,
[[Configurable]]: false }).
Perform ! location.[[DefineOwnProperty]](%Symbol.toPrimitive%, { [[Value]]: undefined, [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }).
Set the value of the [[DefaultProperties]] internal slot of location to location.[[OwnPropertyKeys]]().
Return location.
Location objects provide a representation of the URL of their associated Document, as well as
methods for navigating and reloading
the associated navigable.
The href setter steps are:
If this's relevant Document is null, then
return.
Let url be the result of encoding-parsing a URL given the given value, relative to the entry settings object.
If url is failure, then throw a "SyntaxError"
DOMException.
Location-object navigate this to
url.
The protocol setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
Let possibleFailure be the result of basic URL
parsing the given value, followed by ":", with copyURL
as url and scheme start state as
state override.
If possibleFailure is failure, then throw a
"SyntaxError" DOMException.
If copyURL's scheme is not an HTTP(S) scheme, then terminate these steps.
Location-object navigate this to
copyURL.
The host setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
If copyURL has an opaque path, then return.
Basic URL parse the given value, with copyURL as url and host state as state override.
Location-object navigate this to
copyURL.
The hostname setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
If copyURL has an opaque path, then return.
Basic URL parse the given value, with copyURL as url and hostname state as state override.
Location-object navigate this to
copyURL.
The port setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
If copyURL cannot have a username/password/port, then return.
If the given value is the empty string, then set copyURL's port to null.
Otherwise, basic URL parse the given value, with copyURL as url and port state as state override.
Location-object navigate this to
copyURL.
The pathname setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
If copyURL has an opaque path, then return.
Set copyURL's path to the empty list.
Basic URL parse the given value, with copyURL as url and path start state as state override.
Location-object navigate this to
copyURL.
The search setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
If the given value is the empty string, set copyURL's query to null.
Otherwise, run these substeps:
Let input be the given value with a single leading "?" removed, if any.
Set copyURL's query to the empty string.
Basic URL parse input, with null, the
relevant Document's document's character encoding,
copyURL as url, and query
state as state
override.
Location-object navigate this to
copyURL.
The hash setter steps are:
If this's relevant Document is null, then
return.
If this's relevant Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" DOMException.
Let input be the given value with a single leading "#"
removed, if any.
Set copyURL's fragment to the empty string.
Basic URL parse input, with copyURL as url and fragment state as state override.
If copyURL's fragment is this's url's fragment, then return.
Location-object navigate this to
copyURL.
As explained earlier, the Location exotic object
requires additional logic beyond IDL for security purposes. The Location object must
use the ordinary internal methods except where it is explicitly specified otherwise below.
Also, every Location object has a [[DefaultProperties]] internal slot
representing its own properties at time of its creation.
If IsPlatformObjectSameOrigin(this) is true, then return ! OrdinaryGetPrototypeOf(this).
Return null.
Return ! SetImmutablePrototype(this, V).
Return true.
Return false.
If IsPlatformObjectSameOrigin(this) is true, then:
Let desc be OrdinaryGetOwnProperty(this, P).
If the value of the [[DefaultProperties]] internal slot of this contains P, then set desc.[[Configurable]] to true.
Return desc.
Let property be CrossOriginGetOwnPropertyHelper(this, P).
If property is not undefined, then return property.
Return ? CrossOriginPropertyFallback(P).
If IsPlatformObjectSameOrigin(this) is true, then:
If the value of the [[DefaultProperties]] internal slot of this contains P, then return false.
Return ? OrdinaryDefineOwnProperty(this, P, Desc).
Throw a "SecurityError" DOMException.
If IsPlatformObjectSameOrigin(this) is true, then return ? OrdinaryGet(this, P, Receiver).
Return ? CrossOriginGet(this, P, Receiver).
If IsPlatformObjectSameOrigin(this) is true, then return ? OrdinarySet(this, P, V, Receiver).
Return ? CrossOriginSet(this, P, V, Receiver).
If IsPlatformObjectSameOrigin(this) is true, then return ? OrdinaryDelete(this, P).
Throw a "SecurityError" DOMException.
If IsPlatformObjectSameOrigin(this) is true, then return OrdinaryOwnPropertyKeys(this).
Return CrossOriginOwnPropertyKeys(this).
History interfaceSupport in all current engines.
Support in all current engines.
The history getter steps
are to return this's associated
Document's history object.
The scrollRestoration setter steps
are:
If this's relevant global object's associated Document is not fully
active, then throw a "SecurityError"
DOMException.
Set this's node navigable's active session history entry's scroll restoration mode to the given value.
User agents may limit the number of state objects added to the session history per page. If a
page hits the implementation-defined limit, user agents must remove the entry
immediately after the first entry for that Document object in the session history
after having added the new entry. (Thus the state history acts as a FIFO buffer for eviction, but
as a LIFO buffer for navigation.)
This section is non-normative.
The navigation API, provided by the global navigation
property, provides a modern and web application-focused way of managing navigations and history entries. It is a successor to the classic location and history APIs.
One ability the API provides is inspecting session history entries. For example, the following will display the entries' URLs in an ordered list:
const ol = document. createElement( "ol" );
ol. start = 0 ; // so that the list items' ordinal values match up with the entry indices
for ( const entry of navigation. entries()) {
const li = document. createElement( "li" );
if ( entry. index < navigation. currentEntry. index) {
li. className = "backward" ;
} else if ( entry. index > navigation. currentEntry. index) {
li. className = "forward" ;
} else {
li. className = "current" ;
}
li. textContent = entry. url;
ol. append( li);
}
The navigation.entries() array contains NavigationHistoryEntry instances, which have other useful properties in addition to the url and index properties shown here. Note that the array only contains NavigationHistoryEntry objects that represent the current navigable, and thus its contents are not impacted by navigations inside navigable containers such as iframes, or by navigations of the parent navigable in cases where the navigation API is itself being used inside an iframe. Additionally, it only contains NavigationHistoryEntry objects representing same-origin session history entries, meaning that if the user has visited other origins before or after the current one, there will not be corresponding NavigationHistoryEntrys.
The navigation API can also be used to navigate, reload, or traverse through the history:
Note that traversals are again limited to same-origin destinations, meaning that, for example, navigation.canGoBack will be false if the previous session history entry is for a page from another origin.
The most powerful part of the navigation API is the navigate event, which fires whenever almost any navigation or traversal occurs in the current navigable:
navigation. onnavigate = event => {
console. log( event. navigationType); // "push", "replace", "reload", or "traverse"
console. log( event. destination. url);
console. log( event. userInitiated);
// ... and other useful properties
};
(The event will not fire for location bar-initiated navigations, or navigations initiated from other windows, when the destination of the navigation is a new document.)
Much of the time, the event's cancelable property will be true, meaning this event can be canceled using preventDefault():
navigation. onnavigate = event => {
if ( event. cancelable && isDisallowedURL( event. destination. url)) {
alert( `Please don't go to ${ event. destination. url} !` );
event. preventDefault();
}
};
The cancelable property will be false for some "traverse" navigations, such as those taking place inside child navigables, those crossing to new origins, or when the user attempts to traverse again shortly after a previous call to preventDefault() prevented them from doing so.
The NavigateEvent's intercept() method allows intercepting a navigation and converting it into a same-document navigation:
navigation. addEventListener( "navigate" , e => {
// Some navigations, e.g. cross-origin navigations, we cannot intercept.
// Let the browser handle those normally.
if ( ! e. canIntercept) {
return ;
}
// Similarly, don't intercept fragment navigations or downloads.
if ( e. hashChange || e. downloadRequest !== null ) {
return ;
}
const url = new URL( event. destination. url);
if ( url. pathname. startsWith( "/articles/" )) {
e. intercept({
async handler() {
// The URL has already changed, so show a placeholder while
// fetching the new content, such as a spinner or loading page.
renderArticlePagePlaceholder();
// Fetch the new content and display when ready.
const articleContent = await getArticleContent( url. pathname, { signal: e. signal });
renderArticlePage( articleContent);
}
});
}
});
Note that the handler function can return a promise to represent the asynchronous progress, and success or failure, of the navigation. While the promise is still pending, browser UI can treat the navigation as ongoing (e.g., by presenting a loading spinner). Other parts of the navigation API are also sensitive to these promises, such as the return value of navigation.navigate():
const { committed, finished } = await navigation. navigate( "/articles/the-navigation-api-is-cool" );
// The committed promise will fulfill once the URL has changed, which happens
// immediately (as long as the NavigateEvent wasn't canceled).
await committed;
// The finished promise will fulfill once the Promise returned by handler() has
// fulfilled, which happens once the article is downloaded and rendered. (Or,
// it will reject, if handler() fails along the way).
await finished;
Navigation interfaceThe following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the
Navigation interface:
| Event handler | Event handler event type |
|---|---|
onnavigate
| navigate
|
onnavigatesuccess
| navigatesuccess
|
onnavigateerror
| navigateerror
|
oncurrententrychange
| currententrychange
|
A key type used throughout the navigation API is the NavigationType
enumeration:
This captures the main web developer-visible types of "navigations", which (as noted elsewhere) do not exactly correspond to this standard's singular navigate algorithm. The meaning of each value is the following:
push"push", or to
history.pushState().replace"replace", or
to history.replaceState().reload"traverse"NavigationHistoryEntry interfaceThe following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the
NavigationHistoryEntry interface:
| Event handler | Event handler event type |
|---|---|
ondispose
| dispose
|
A navigation API method tracker-derived result for a navigation API method
tracker is a NavigationResult dictionary instance given by «[ "committed" → apiMethodTracker's committed promise, "finished" → apiMethodTracker's finished promise ]».
During any given navigation (in the broad sense of the
word), the Navigation object needs to keep track of the following:
| State | Duration | Explanation |
|---|---|---|
The NavigateEvent
| For the duration of event firing | So that if the navigation is canceled while the event is firing, we can cancel the event |
| The event's abort controller | Until all promises returned from handlers passed to intercept() have settled
| So that if the navigation is canceled, we can signal abort |
| Whether a new element was focused | Until all promises returned from handlers passed to intercept() have settled
| So that if one was, focus is not reset |
The NavigationHistoryEntry being navigated to
| From when it is determined, until all promises returned from handlers passed to intercept() have settled
| So that we know what to resolve any committed and finished promises with
|
Any finished promise that was returned
| Until all promises returned from handlers passed to intercept() have settled
| So that we can resolve or reject it appropriately |
| State | Duration | Explanation |
|---|---|---|
Any state
| For the duration of event firing | So that we can update the current entry's navigation API state if the event finishes firing without being canceled |
| State | Duration | Explanation |
|---|---|---|
Any info
| Until the task is queued to fire the navigate event
| So that we can use it to fire the navigate after the trip through the session history traversal queue.
|
Any committed promise that was returned
| Until the session history is updated (inside that same task) | So that we can resolve or reject it appropriately |
Whether intercept() was called
| Until the session history is updated (inside that same task) | So that we can suppress the normal scroll restoration logic in favor of the behavior given by the scroll option
|
We also cannot assume there is only a single navigation requested at any given time, due to web developer code such as:
const p1 = navigation. navigate( url1). finished;
const p2 = navigation. navigate( url2). finished;
That is, in this scenario, we need to ensure that while navigating to url2, we still have the promise p1 around so that we can
reject it. We can't just get rid of any ongoing navigation promises the moment the second call to
navigate() happens.
We end up accomplishing all this by associating the following with each
Navigation:
All this state is then managed via the following algorithms.
The ongoing navigation concept is most-directly exposed to web developers through the navigation.transition property, which is an instance of
the NavigationTransition interface:
The finished getter steps are to return
this's finished
promise.
NavigationActivation interfaceEach NavigationActivation has:
The navigationType getter steps are to
return this's navigation type.
navigate eventA major feature of the navigation API is the navigate
event. This event is fired on any navigation (in the broad sense of
the word), allowing web developers to monitor such outgoing navigations. In many cases, the
event is cancelable, which allows preventing the
navigation from happening. And in others, the navigation can be intercepted and replaced with a
same-document navigation by using the intercept() method of the NavigateEvent
class.
NavigateEvent interfaceNavigationDestination interfaceEach NavigationDestination has an is same document, which is a
boolean.
The getState() method steps are to return
StructuredDeserialize(this's state).
Other parts of the standard fire the navigate event,
through a series of wrapper algorithms given in this section.
To fire a traverse navigate event at a
Navigation navigation given a session history entry destinationSHE and an optional
user navigation involvement userInvolvement (default "none"):
Let event be the result of creating an event given
NavigateEvent, in navigation's relevant realm.
Set event's classic history API state to null.
Let destination be a new NavigationDestination
created in navigation's relevant
realm.
Let destinationNHE be the NavigationHistoryEntry in
navigation's entry list whose session history entry is destinationSHE, or null if no such
NavigationHistoryEntry exists.
If destinationNHE is non-null, then:
Set destination's entry to destinationNHE.
Set destination's state to destinationSHE's navigation API state.
Otherwise,
Set destination's entry to null.
Set destination's state to StructuredSerializeForStorage(null).
Set destination's is
same document to true if destinationSHE's document is equal to navigation's relevant global
object's associated Document;
otherwise false.
Return the result of performing the inner navigate event firing algorithm given
navigation, "traverse",
event, destination, userInvolvement, null, and null.
To fire a push/replace/reload navigate event at
a Navigation navigation given a NavigationType navigationType, a URL destinationURL, a boolean isSameDocument, an optional user
navigation involvement userInvolvement (default "none"), an optional entry list-or-null formDataEntryList (default null), an
optional serialized state navigationAPIState (default
StructuredSerializeForStorage(null)), and an optional serialized
state-or-null classicHistoryAPIState (default
null):
Let event be the result of creating an event given
NavigateEvent, in navigation's relevant realm.
Set event's classic history API state to classicHistoryAPIState.
Let destination be a new NavigationDestination
created in navigation's relevant
realm.
Set destination's URL to destinationURL.
Set destination's entry to null.
Set destination's state to navigationAPIState.
Set destination's is same document to isSameDocument.
Return the result of performing the inner navigate event firing algorithm given
navigation, navigationType, event, destination,
userInvolvement, formDataEntryList, and null.
To fire a download request navigate event at a
Navigation navigation given a URL destinationURL, a user
navigation involvement userInvolvement, and a string
filename:
Let event be the result of creating an event given
NavigateEvent, in navigation's relevant realm.
Set event's classic history API state to null.
Let destination be a new NavigationDestination
created in navigation's relevant
realm.
Set destination's URL to destinationURL.
Set destination's entry to null.
Set destination's state to StructuredSerializeForStorage(null).
Set destination's is same document to false.
Return the result of performing the inner navigate event firing algorithm given
navigation, "push", event,
destination, userInvolvement, null, and filename.
By calling navigateEvent.intercept(), web
developers can suppress the normal scroll and focus behavior for same-document navigations,
instead invoking cross-document navigation-like behavior at a later time. The algorithms in this
section are called at those appropriate later points.
NavigationCurrentEntryChangeEvent interfaceThe navigationType and from attributes must return the
values they were initialized to.
PopStateEvent interfaceSupport in all current engines.
Support in all current engines.
The
hasUAVisualTransition attribute must return the value it was initialized to.
HashChangeEvent interfaceHashChangeEvent/HashChangeEvent
Support in all current engines.
Support in all current engines.
The newURL attribute must return the value it was
initialized to. It represents context information for the event, specifically the URL of the
session history entry that was traversed to.
PageSwapEvent interfaceThe activation and viewTransition attributes must return
the values they were initialized to.
PageRevealEvent interfaceThe viewTransition attribute must return the
value it was initialized to.
PageTransitionEvent interfacePageTransitionEvent/PageTransitionEvent
Support in all current engines.
Support in all current engines.
To fire a page transition event named eventName at a Window
window with a boolean persisted, fire
an event named eventName at window, using
PageTransitionEvent, with the persisted attribute initialized to
persisted, the cancelable attribute
initialized to true, the bubbles attribute initialized to
true, and legacy target override flag set.
BeforeUnloadEvent interfaceSupport in all current engines.
The BeforeUnloadEvent interface is a legacy interface which allows checking
if unloading is canceled to be controlled not only by canceling the event, but by setting
the returnValue attribute to a value
besides the empty string. Authors should use the preventDefault() method, or other means of canceling
events, instead of using returnValue.
The returnValue attribute controls the process
of checking if unloading is canceled. When the event is created, the
attribute must be set to the empty string. On getting, it must return the last value it was set
to. On setting, the attribute must be set to the new value.
NotRestoredReasons interfaceThe reason is a string that represents the reason that prevented the page from being restored from back/forward cache. The string is one of the following:
fetch"Document was still ongoing and was canceled, so the page was not in a state that
could be stored in the back/forward cache.navigation-failure"Document errored, so storing the
resulting error document in the back/forward cache was
prevented.parser-aborted"Document never finished its initial HTML parsing, so storing the unfinished
document in the back/forward cache was prevented.websocket"WebSocket
connection was shut down, so the page was not in a state that could be stored in the back/forward cache. [WEBSOCKETS]lock"masked"Document has children that are in a cross-origin iframe, and
they prevented back/forward cache; or this Document
could not be back/forward cached for user agent-specific reasons, and
the user agent has chosen not to use one of the more specific reasons from the list of user-agent specific blocking reasons.
A Document's not restored reasons is its node navigable's
active session history entry's document state's not restored reasons, if
Document's node navigable is a top-level traversable;
otherwise null.
This standard contains several related concepts for grouping sequences of documents. As a brief, non-normative summary:
Navigables are a user-facing representation of a sequence
of documents, i.e., they represent something that can be navigated between documents. Typical
examples are tabs or windows in a web browser, or iframes, or
frames in a frameset.
Traversable navigables are a special type of navigable which control the session history of themselves and of their descendant navigables. That is, in addition to their own series of documents, they represent a tree of further series of documents, plus the ability to linearly traverse back and forward through a flattened view of this tree.
Browsing contexts are a developer-facing
representation of a series of documents. They correspond 1:1 with WindowProxy
objects. Each navigable can present a series of browsing contexts, with switches between
those browsing contexts occuring under certain well-defined circumstances.
Most of this standard works in the language of navigables, but certain APIs expose the existence of browsing context switches, and so some parts of the standard need to work in terms of browsing contexts.
The current session history entry and the active session history entry are usually the same, but they get out of sync when:
Synchronous navigations are performed. This causes the active session history entry to temporarily step ahead of the current session history entry.
A non-displayable, non-error response is received when applying the history step. This updates the current session history entry but leaves the active session history entry as-is.
A navigable's target name is its active session history entry's document state's navigable target name.
To get the node navigable of a node node, return the navigable whose active document is node's node document, or null if there is no such navigable.
In addition to the properties of a navigable, a traversable navigable has:
See the page visibility section for the requirements on this item.
A useful method for visualizing sequences of documents, and in particular navigables and their session history entries, is the Jake diagram. A typical Jake diagram is the following:
| 0 | 1 | 2 | 3 | 4 | |
|---|---|---|---|---|---|
top | /t-a | /t-a#foo | /t-b | ||
frames[0] | /i-0-a | /i-0-b | |||
frames[1] | /i-1-a | /i-1-b | |||
Here, each numbered column denotes a possible value for the traversable's session history step. Each labeled row depicts a
navigable, as it transitions between different URLs and documents. The first,
labeled top, being the top-level traversable, and the others
being child navigables. The documents are given by the
background color of each cell, with a new background color indicating a new document in that
navigable. The URLs are given by the text content of the cells; usually they are
given as relative URLs for brevity, unless a cross-origin case
is specifically under investigation. A given navigable might not exist at a given step, in which
case the corresponding cells are empty. The bold-italic step number depicts the current session history step of the traversable,
and all cells with bold-italic URLs represent the current session history entry for that row's
navigable.
Thus, the above Jake diagram depicts the following sequence of events:
A top-level traversable is created, starting a the URL /t-a, with two child navigables
starting at /i-0-a and /i-1-a
respectively.
The first child navigable is navigated to another
document, with URL /i-0-b.
The second child navigable is navigated to another
document, with URL /i-1-b.
The top-level traversable is navigated to the
same document, updating its URL to /t-a#foo.
The top-level traversable is navigated to another
document, with URL /t-b. (Notice how this document, of course, does not
carry over the old document's child navigables.)
The traversable was traversed by a delta of −3, back to step 1.
Jake diagrams are a powerful tool for visualizing the interactions of multiple navigables, navigations, and traversals. They cannot capture every possible interaction — for example, they only work with a single level of nesting — but we will have ocassion to use them to illustrate several complex situations throughout this standard.
It is often helpful in this standard's algorithms to look at collections of navigables starting at a given Document. This section
contains a curated set of algorithms for collecting those navigables.
User agents may destroy a top-level traversable at any time (typically, in response to user requests).
Navigables can be given target
names, which are strings allowing certain APIs (such as window.open() or the a element's target attribute) to target navigations at that navigable.
These values have different meanings based on whether the page is sandboxed or not, as
summarized in the following (non-normative) table. In this table, "current" means the
navigable that the link or script is in, "parent" means the parent of the navigable that the link or script is in,
"top" means the top-level traversable of the navigable
that the link or script is in, "new" means a new traversable navigable with a null
parent (which may use an auxiliary browsing
context, subject to various user preferences and user agent policies), "none" means that
nothing will happen, and "maybe new" means the same as "new" if the "allow-popups" keyword is also specified on the
sandbox attribute (or if the user overrode the
sandboxing), and the same as "none" otherwise.
| Keyword | Ordinary effect | Effect in an iframe with...
| |
|---|---|---|---|
sandbox=""
| sandbox="allow-top-navigation"
| ||
| none specified, for links and form submissions | current | current | current |
| empty string | current | current | current |
_blank
| new | maybe new | maybe new |
_self
| current | current | current |
_parent if there isn't a parent
| current | current | current |
_parent if parent is also top
| parent/top | none | parent/top |
_parent if there is one and it's not top
| parent | none | none |
_top if top is current
| current | current | current |
_top if top is not current
| top | none | top |
| name that doesn't exist | new | maybe new | maybe new |
| name that exists and is a descendant | specified descendant | specified descendant | specified descendant |
| name that exists and is current | current | current | current |
| name that exists and is an ancestor that is top | specified ancestor | none | specified ancestor/top |
| name that exists and is an ancestor that is not top | specified ancestor | none | none |
| other name that exists with common top | specified | none | none |
| name that exists with different top, if familiar and one permitted sandboxed navigator | specified | specified | specified |
| name that exists with different top, if familiar but not one permitted sandboxed navigator | specified | none | none |
| name that exists with different top, not familiar | new | maybe new | maybe new |
Most of the restrictions on sandboxed browsing contexts are applied by other algorithms, e.g. the navigation algorithm, not the rules for choosing a navigable given below.
A browsing context's active window is its WindowProxy
object's [[Window]] internal slot value. A
browsing context's active document is its active window's
associated Document.
A browsing context whose is auxiliary is true is known as an auxiliary browsing context. Auxiliary browsing contexts are always top-level browsing contexts.
A Document's browsing context is a browsing context or null,
initially null.
A browsing context group holds a browsing context set (a set of top-level browsing contexts).
A cross-origin isolation mode is one of three possible values: "none", "logical", or "concrete".
When there are no Document objects whose
browsing context equals a given browsing
context (i.e., all such Documents have been destroyed), and that browsing context's WindowProxy is
eligible for garbage collection, then the browsing context will never be accessed
again. If it is a top-level browsing context, then at this point the user agent must
remove it.
Because they are associated with an element, child
navigables are always tied to a specific Document, their container document, in their parent navigable. User agents must not allow the user to interact with
child navigables whose container documents are not themselves fully
active.
Welcome to the dragon's maw. Navigation, session history, and the traversal through that session history are some of the most complex parts of this standard.
The basic concept may not seem so difficult:
The user is looking at a navigable that is presenting its active document. They navigate it to another URL.
The browser fetches the given URL from the network, using it to populate a new session history entry
with a newly-created
Document.
The browser updates the navigable's active session history entry to the newly-populated one, and thus updates the active document that it is showing to the user.
At some point later, the user presses the browser back button to go back to the previous session history entry.
The browser looks at the URL stored in that session history entry, and uses it to re-fetch and populate that entry's document.
The browser again updates the navigable's active session history entry.
You can see some of the intertwined complexity peeking through here, in how traversal can cause a navigation (i.e., a network fetch to a stored URL), and how a navigation necessarily needs to interface with the session history list to ensure that when it finishes the user is looking at the right thing. But the real problems come in with the various edge cases and interacting web platform features:
Child navigables (e.g., those contained in
iframes) can also navigate and traverse, but those navigations need to be
linearized into a single session history list
since the user only has a single back/forward interface for the entire traversable
navigable (e.g., browser tab).
Since the user can traverse back more than a single step in the session history (e.g., by holding down their back button), they can end up traversing multiple navigables at the same time when child navigables are involved. This needs to be synchronized across all of the involved navigables, which might involve multiple event loops or even agent clusters.
During navigation, servers can respond with 204 or 205 status codes or with `Content-Disposition: attachment` headers, which cause
navigation to abort and the navigable to stay on its original active document. (This is much worse if it happens during a traversal-initiated
navigation!)
Various other HTTP headers, such as `Location`,
`Refresh`, `X-Frame-Options`, and those for Content Security Policy,
contribute to either the fetching
process, or the Document-creation
process, or both. The `Cross-Origin-Opener-Policy` header even contributes
to the browsing
context selection and creation process!
Some navigations (namely fragment navigations and single-page app navigations) are synchronous, meaning that JavaScript code expects to observe the navigation's results instantly. This then needs to be synchronized with the view of the session history that all other navigables in the tree see, which can be subject to race conditions and necessitate resolving conflicting views of the session history.
The platform has accumulated various exciting navigation-related features that need
special-casing, such as javascript: URLs, srcdoc iframes, and the beforeunload event.
In what follows, we have attempted to guide the reader through these complexities by appropriately cordoning them off into labeled sections and algorithms, and giving appropriate words of introduction where possible. Nevertheless, if you wish to truly understand navigation and session history, the usual advice will be invaluable.
To get a session history entry's document, return its document state's document.
Pages can add serialized state to the session history. These are then deserialized and returned to the script when the user (or script) goes back in the history, thus enabling authors to use the "navigation" metaphor even in one-page applications.
User agents may destroy a document and its descendants given the documents of document
states with non-null documents, as long as
the Document is not fully active.
Apart from that restriction, this standard does not specify when user agents should destroy the document stored in a document state, versus keeping it cached.
Several contiguous entries in a session history can share the same document state. This can occur when the initial entry is
reached via normal navigation, and the following entry is added
via history.pushState(). Or it can occur via navigation to a fragment.
A Document has a latest entry, a session history entry or
null.
To maintain a single source of truth, all modifications to a traversable navigable's session history entries need to be synchronized. This is especially important due to how session history is influenced by all of the descendant navigables, and thus by multiple event loops. To accomplish this, we use the session history traversal parallel queue structure.
A session history traversal parallel queue is very similar to a parallel queue. It has an algorithm set, an ordered set.
The items in a session history traversal parallel queue's algorithm set are either algorithm steps, or synchronous navigation steps, which are a particular brand of algorithm steps involving a target navigable (a navigable).
This section contains a miscellaneous grab-bag of operations that we perform throughout the standard when manipulating session history. The best way to get a sense of what they do is to look at their call sites.
Certain actions cause a navigable to navigate to a new resource.
Before we can jump into the navigation algorithm itself, we need to establish several important structures that it uses.
To snapshot target snapshot params given a navigable targetNavigable, return a new target snapshot params with sandboxing flags set to the result of determining the creation sandboxing flags given targetNavigable's active browsing context and targetNavigable's container.
A navigation ID is a UUID string generated during navigation. It is used to interface with the WebDriver BiDi specification as well as to track the ongoing navigation. [WEBDRIVERBIDI]
After Document creation, the relevant traversable navigable's session history gets updated. The
NavigationHistoryBehavior enumeration is used to indicate the desired type of session
history update to the navigate algorithm. It is one of the following:
push"replace"auto"push" or "replace". Usually it becomes "push", but under certain circumstances it becomes "replace" instead.To navigate a navigable navigable to a
URL url using a Document sourceDocument, with an optional POST resource,
string, or null documentResource (default null), an optional response-or-null response (default null), an optional boolean
exceptionsEnabled (default
false), an optional NavigationHistoryBehavior historyHandling (default "auto"), an optional serialized
state-or-null navigationAPIState (default null), an optional entry list or
null formDataEntryList (default null), an optional referrer
policy referrerPolicy (default
the empty string), and an optional user navigation involvement userInvolvement (default "none"):
Let cspNavigationType be "form-submission" if
formDataEntryList is non-null; otherwise "other".
Let sourceSnapshotParams be the result of snapshotting source snapshot params given sourceDocument.
Let initiatorOriginSnapshot be sourceDocument's origin.
Let initiatorBaseURLSnapshot be sourceDocument's document base URL.
If sourceDocument's node navigable is not allowed by sandboxing to navigate navigable given sourceSnapshotParams, then:
If exceptionsEnabled is true, then throw a
"SecurityError" DOMException.
Return.
Let navigationId be the result of generating a random UUID. [WEBCRYPTO]
If the surrounding agent is equal to navigable's active document's relevant agent, then continue these steps. Otherwise, queue a global task on the navigation and traversal task source given navigable's active window to continue these steps.
If navigable's active document's
unload counter is greater than 0, then invoke WebDriver BiDi navigation
failed with navigable and a WebDriver BiDi navigation status whose
id is navigationId, status is "canceled", and url is url, and return.
Let container be navigable's container.
If container is an iframe element and will lazy load
element steps given container returns true, then stop
intersection-observing a lazy loading element container and set
container's lazy load resumption steps to null.
If the navigation must be a replace given url and
navigable's active document, then set
historyHandling to "replace".
If navigable's parent is non-null, then set
navigable's is delaying load events to
true.
Let targetSnapshotParams be the result of snapshotting target snapshot params given navigable.
Invoke WebDriver BiDi navigation started with navigable and a new
WebDriver BiDi navigation status whose id
is navigationId, status is "pending", and url is url.
If navigable's ongoing navigation is "traversal", then:
Invoke WebDriver BiDi navigation failed with navigable and a new
WebDriver BiDi navigation status whose id is navigationId, status is "canceled", and url is url.
Return.
Set the ongoing navigation for navigable to navigationId.
If url's scheme is "javascript", then:
Queue a global task on the navigation and traversal task
source given navigable's active window to
navigate to a javascript: URL given navigable,
url, historyHandling, initiatorOriginSnapshot,
userInvolvement, and cspNavigationType.
Return.
If all of the following are true:
userInvolvement is not "browser
UI";
navigable's active document's origin is same origin-domain with sourceDocument's origin;
navigable's active document's is
initial about:blank is false; and
url's scheme is a fetch scheme,
then:
Let navigation be navigable's active window's navigation API.
Let entryListForFiring be formDataEntryList if documentResource is a POST resource; otherwise, null.
Let navigationAPIStateForFiring be navigationAPIState if navigationAPIState is not null; otherwise, StructuredSerializeForStorage(undefined).
Let continue be the result of firing a push/replace/reload navigate
event at navigation with navigationType set to historyHandling,
isSameDocument set to false, userInvolvement set to
userInvolvement, formDataEntryList set to
entryListForFiring, destinationURL
set to url, and navigationAPIState set to
navigationAPIStateForFiring.
If continue is false, then return.
In parallel, run these steps:
Let unloadPromptCanceled be the result of checking if unloading is canceled for navigable's active document's inclusive descendant navigables.
If unloadPromptCanceled is true, or navigable's ongoing navigation is no longer navigationId, then:
Invoke WebDriver BiDi navigation failed with navigable and a
new WebDriver BiDi navigation status whose id is navigationId, status is "canceled", and url is url.
Abort these steps.
Queue a global task on the navigation and traversal task source given navigable's active window to abort a document and its descendants given navigable's active document.
If url matches about:blank or
is about:srcdoc, then:
Set documentState's origin to initiatorOriginSnapshot.
Set documentState's about base URL to initiatorBaseURLSnapshot.
Let historyEntry be a new session history entry, with its URL set to url and its document state set to documentState.
Let navigationParams be null.
If response is non-null:
Let policyContainer be the result of determining navigation params policy container given response's URL, null, a clone of the sourceDocument's policy container, navigable's container document's policy container, and null.
Let finalSandboxFlags be the union of targetSnapshotParams's sandboxing flags and policyContainer's CSP list's CSP-derived sandboxing flags.
Let responseOrigin be the result of determining the origin given response's URL, finalSandboxFlags, and documentState's initiator origin.
Let coop be a new opener policy.
Let coopEnforcementResult be a new opener policy enforcement result with
Set navigationParams to a new navigation params, with
navigate"Attempt to populate the history entry's document for historyEntry,
given navigable, "navigate", sourceSnapshotParams,
targetSnapshotParams, userInvolvement, navigationId,
navigationParams, cspNavigationType, with allowPOST set to true and completionSteps set to the following
step:
Append session history traversal steps to navigable's traversable to finalize a cross-document navigation given navigable, historyHandling, userInvolvement, and historyEntry.
Although the usual cross-document navigation case will first foray into populating a session history entry with a
Document, all navigations that don't get aborted will ultimately end up calling into
one of the below algorithms.
A couple of scenarios can intervene early in the navigation process and put the whole thing to a halt. This can be especially exciting when multiple navigables are navigating at the same time, due to a session history traversal.
To reload a navigable navigable given an optional
serialized state-or-null navigationAPIState (default null) and an
optional user navigation involvement userInvolvement (default "none"):
If userInvolvement is not "browser UI",
then:
Let navigation be navigable's active window's navigation API.
Let destinationNavigationAPIState be navigable's active session history entry's navigation API state.
If navigationAPIState is not null, then set destinationNavigationAPIState to navigationAPIState.
Let continue be the result of firing a push/replace/reload navigate
event at navigation with navigationType set to "reload", isSameDocument set to false, userInvolvement set to
userInvolvement, destinationURL
set to navigable's active session history
entry's URL, and navigationAPIState set to
destinationNavigationAPIState.
If continue is false, then return.
Set navigable's active session history entry's document state's reload pending to true.
Let traversable be navigable's traversable navigable.
Append the following session history traversal steps to traversable:
Apply the reload history step to traversable given userInvolvement.
To traverse the history by a delta given a traversable navigable
traversable, an integer delta, and an optional Document sourceDocument:
Let sourceSnapshotParams and initiatorToCheck be null.
Let userInvolvement be "browser
UI".
If sourceDocument is given, then:
Set sourceSnapshotParams to the result of snapshotting source snapshot params given sourceDocument.
Set initiatorToCheck to sourceDocument's node navigable.
Set userInvolvement to "none".
Append the following session history traversal steps to traversable:
Let allSteps be the result of getting all used history steps for traversable.
Let currentStepIndex be the index of traversable's current session history step within allSteps.
Let targetStepIndex be currentStepIndex plus delta.
If allSteps[targetStepIndex] does not exist, then abort these steps.
Apply the traverse history step allSteps[targetStepIndex] to traversable, given sourceSnapshotParams, initiatorToCheck, and userInvolvement.
Apart from the navigate algorithm, session
history entries can be pushed or replaced via one more mechanism, the URL and
history update steps. The most well-known callers of these steps are the history.replaceState() and history.pushState() APIs, but various other parts of the
standard also need to perform updates to the active
history entry, and they use these steps to do so.
The URL and history update steps, given a Document
document, a URL newURL, an optional serialized
state-or-null serializedData (default
null), and an optional history handling behavior historyHandling (default "replace"), are:
Let navigable be document's node navigable.
Let activeEntry be navigable's active session history entry.
Let newEntry be a new session history entry, with
If document's is initial about:blank is true, then set
historyHandling to "replace".
Let entryToReplace be activeEntry if historyHandling is
"replace", otherwise null.
If historyHandling is "push",
then:
Increment document's history object's index.
Set document's history object's length to its index + 1.
If serializedData is not null, then restore the history object state given document and newEntry.
Set document's URL to newURL.
Set document's latest entry to newEntry.
Set navigable's active session history entry to newEntry.
Update the navigation API entries for a same-document navigation given document's relevant global object's navigation API, newEntry, and historyHandling.
Let traversable be navigable's traversable navigable.
Append the following session history synchronous navigation steps involving navigable to traversable:
Finalize a same-document navigation given traversable,
navigable, newEntry, entryToReplace,
historyHandling, and "none".
Invoke WebDriver BiDi history updated with navigable.
As explained in the overview, both navigation and traversal involve creating a session history entry and then attempting to populate its document member, so that it can be presented inside the navigable.
This involves either: using an already-given
response; using the srcdoc resource stored in
the session history entry; or fetching. The process has several failure modes, which can either result in
doing nothing (leaving the navigable on its currently-active Document) or can result in populating the
session history entry with an error
document.
To attempt to populate the history entry's document for a session history
entry entry, given a navigable navigable, a
NavigationTimingType navTimingType, a source snapshot params
sourceSnapshotParams, a target snapshot params
targetSnapshotParams, a user navigation involvement
userInvolvement, an optional navigation ID-or-null navigationId
(default null), an optional navigation params-or-null navigationParams
(default null), an optional string cspNavigationType (default "other"), an optional boolean allowPOST (default false), and optional
algorithm steps completionSteps (default an empty
algorithm):
Assert: this is running in parallel.
Assert: if navigationParams is non-null, then navigationParams's response is non-null.
Let documentResource be entry's document state's resource.
If navigationParams is null, then:
If documentResource is a string, then set navigationParams to the result of creating navigation params from a srcdoc resource given entry, navigable, targetSnapshotParams, userInvolvement, navigationId, and navTimingType.
Otherwise, if all of the following are true:
entry's URL's scheme is a fetch scheme; and
documentResource is null, or allowPOST is true and documentResource's request body is not failure,
then set navigationParams to the result of creating navigation params by fetching given entry, navigable, sourceSnapshotParams, targetSnapshotParams, cspNavigationType, userInvolvement, navigationId, and navTimingType.
Otherwise, if entry's URL's scheme is not a fetch scheme, then set navigationParams to a new non-fetch scheme navigation params, with
For both navigation and traversal, once we have an idea of where we want to head to in the
session history, much of the work comes about in applying that notion to the traversable
navigable and the relevant Document. For navigations, this work generally
occurs toward the end of the process; for traversals, it is the beginning.
Ensuring a traversable ends up at the right session history step is particularly complex, as it can involve coordinating across multiple navigable descendants of the traversable, populating them in parallel, and then synchronizing back up to ensure everyone has the same view of the result. This is further complicated by the existence of synchronous same-document navigations being mixed together with cross-document navigations, and how web pages have come to have certain relative timing expectations.
Although all updates to the traversable navigable end up in the same apply the history step algorithm, each possible entry point comes along with some minor customizations:
Now for the algorithm itself.
For an HTML document document, its indicated part is the result of selecting the indicated part given document and document's URL.
When faced with displaying an XML file inline, provided navigation params
navigationParams and a string type, user agents must follow the
requirements defined in XML and Namespaces in XML, XML Media
Types, DOM, and other relevant specifications to create and initialize a Document object
document, given "xml", type, and
navigationParams, and return that Document. They must also create a
corresponding XML parser. [XML] [XMLNS] [RFC7303]
[DOM]
The first task that the networking task source
places on the task queue while fetching runs must process link headers
given document, navigationParams's response, and "media", after
the task has been processed by the XML parser.
The actual HTTP headers and other metadata, not the headers as mutated or implied by the algorithms given in this specification, are the ones that must be used when determining the character encoding according to the rules given in the above specifications. Once the character encoding is established, the document's character encoding must be set to that character encoding.
Before any script execution occurs, the user agent must wait for scripts may run for the
newly-created document to be true for the newly-created Document.
Once parsing is complete, the user agent must set document's during-loading navigation ID for WebDriver BiDi to null.
Error messages from the parse process (e.g., XML namespace well-formedness errors) may be
reported inline by mutating the Document.
The rules for how to convert the bytes of the plain text document into actual characters, and the rules for actually rendering the text to the user, are defined by the specifications for the computed MIME type of the resource (i.e., type).
multipart/x-mixed-replace
documentsFor the purposes of algorithms processing these body parts as if they were complete stand-alone resources, the user agent must act as if there were no more bytes for those resources whenever the boundary following the body part is reached.
The element host element to create for the media is the element given in the table below in the second cell of the row whose first cell describes the media. The appropriate attribute to set is the one given by the third cell in that same row.
| Type of media | Element for the media | Appropriate attribute |
|---|---|---|
| Image | img
| src
|
| Video | video
| src
|
| Audio | audio
| src
|
Before any script execution occurs, the user agent must wait for scripts may run for the
newly-created document to be true for the Document.
When the user agent is to create a document to display a user agent page or PDF viewer inline,
provided a navigable navigable, a navigation ID
navigationId, a NavigationTimingType navTimingType, and a
user navigation involvement userInvolvement, the user agent should:
Let origin be a new opaque origin.
Let coop be a new opener policy.
Let coopEnforcementResult be a new opener policy enforcement result with
Let navigationParams be a new navigation params with
Let document be the result of creating and initializing a Document
object given "html", "text/html", and
navigationParams.
Either associate document with a custom rendering that is not rendered using
the normal Document rendering rules, or mutate document until it
represents the content the user agent wants to render.
Return document.
Once the page has been set up, the user agent must act as if it had stopped parsing.
X-Frame-Options` headerSupport in all current engines.
For web developers and conformance checkers, its value ABNF is:
X-Frame-Options = "DENY" / "SAMEORIGIN"
Refresh` headerThe `Refresh` HTTP response header is the HTTP-equivalent
to a meta element with an http-equiv
attribute in the Refresh state. It takes the same value and works largely the
same. Its processing model is detailed in create and initialize a Document
object.
Browser user agents should provide the ability to navigate, reload, and stop loading any top-level traversable in their top-level traversable set.
Browser user agents should provide the ability to traverse by a delta any top-level traversable in their top-level traversable set.
It is suggested that such user agents allow traversal by deltas greater than one, to avoid
letting a page "trap" the user by stuffing the session history with spurious entries. (For
example, via repeated calls to history.pushState() or
fragment navigations.)
Browser user agents should offer users the ability to create a fresh top-level traversable, given a user-provided or user agent-determined initial URL.
Browser user agents should offer users the ability to arbitrarily close any top-level traversable in their top-level traversable set.
Browser user agents may provide ways for the user to explicitly cause any navigable (not just a top-level traversable) to navigate, reload, or stop loading.
Browser user agents may provide the ability for users to destroy a top-level traversable.
When a user requests a reload of a navigable whose active session history entry's document state's resource is a POST resource, the user agent should prompt the user to confirm the operation first, since otherwise transactions (e.g., purchases or database modifications) could be repeated.
When a user requests a reload of a navigable, user agents may provide a mechanism for ignoring any caches when reloading.
All calls to navigate initiated by the mechanisms mentioned above must have the userInvolvement argument set to "browser UI".
All calls to reload initiated by the mechanisms mentioned above must have the userInvolvement argument set to "browser UI".
All calls to traverse the history by a delta initiated by the mechanisms mentioned above must not pass a value for the sourceDocument argument.
The above recommendations, and the data structures in this specification, are not meant to place restrictions on how user agents represent the session history to the user.
For example, although a top-level traversable's session history entries are stored and maintained as a list, and the user agent is recommended to give an interface for traversing that list by a delta, a novel user agent could instead or in addition present a tree-like view, with each page having multiple "forward" pages that the user can choose between.
Similarly, although session history for all descendant navigables is stored in their traversable navigable, user agents could present the user with a more nuanced per-navigable view of the session history.
Browser user agents may use a top-level browsing context's is popup boolean for the following purposes:
Deciding whether or not to provide a minimal web browser user interface for the corresponding top-level traversable.
Performing the optional steps in set up browsing context features.
In both cases user agents might additionally incorporate user preferences, or present a choice as to whether to go down the popup route.
User agents that provides a minimal user interface for such popups are encouraged to not hide the browser's location bar.
Various mechanisms can cause author-provided executable code to run in the context of a document. These mechanisms include, but are probably not limited to:
script elements.javascript: URLs.addEventListener(), by explicit event handler content attributes, by
event handler IDL attributes, or otherwise.JavaScript defines the concept of an agent. This section gives the mapping of that language-level concept on to the web platform.
The following types of agents exist on the web platform:
Contains various Window objects which can potentially reach each other, either
directly or by using document.domain.
If the encompassing agent cluster's is origin-keyed is true, then
all the Window objects will be same origin, can reach each other
directly, and document.domain will no-op.
Contains a single DedicatedWorkerGlobalScope.
Contains a single SharedWorkerGlobalScope.
Contains a single ServiceWorkerGlobalScope.
Contains a single WorkletGlobalScope object.
Only shared and dedicated worker agents allow the use of JavaScript Atomics APIs to
potentially block.
The relevant agent for a platform object platformObject is platformObject's relevant realm's agent.
JavaScript also defines the concept of an agent cluster, which this standard maps to the web platform by placing agents appropriately when they are created using the obtain a similar-origin window agent or obtain a worker/worklet agent algorithms.
The agent cluster concept is crucial for defining the JavaScript memory model, and
in particular among which agents the backing data of
SharedArrayBuffer objects can be shared.
An agent cluster has an associated is origin-keyed (a boolean), which is initially false.
The following defines the allocation of the agent clusters of similar-origin window agents.
The following defines the allocation of the agent clusters of all other types of agents.
To obtain a service worker agent, return the result of obtaining a worker/worklet agent given null, true, and false.
The JavaScript specification introduces the realm concept, representing a global environment in which script is run. Each realm comes with an implementation-defined global object; much of this specification is devoted to defining that global object and its properties.
For web specifications, it is often useful to associate values or algorithms with a
realm/global object pair. When the values are specific to a particular type of realm, they are
associated directly with the global object in question, e.g., in the definition of the
Window or WorkerGlobalScope interfaces. When the values have utility
across multiple realms, we use the environment settings object concept.
Finally, in some cases it is necessary to track associated values before a realm/global object/environment settings object even comes into existence (for example, during navigation). These values are tracked in the environment concept.
Specifications may define environment discarding steps for environments. The steps take an environment as input.
An environment settings object's responsible event loop is its global object's relevant agent's event loop.
A global object has a resolved module set, a set of specifier resolution records, initially empty.
There is always a 1-to-1-to-1 mapping between realms, global objects, and environment settings objects:
Each global object in this specification is created alongside a corresponding environment settings object, known as its relevant settings object.
When defining algorithm steps throughout this specification, it is often important to indicate what realm is to be used—or, equivalently, what global object or environment settings object is to be used. In general, there are at least four possibilities:
Note how the entry, incumbent, and current concepts are usable without qualification, whereas the relevant concept must be applied to a particular platform object.
In general, web platform specifications should use the relevant concept, applied to the object being operated
on (usually the this value of the current method). This mismatches the JavaScript
specification, where current is generally used as
the default (e.g., in determining the realm whose Array
constructor should be used to construct the result in Array.prototype.map).
But this inconsistency is so embedded in the platform that we have to accept it going forward.
The rest of this section deals with formally defining the entry, incumbent, current, and relevant concepts.
The process of calling scripts will push or pop realm execution contexts onto the JavaScript execution context stack, interspersed with other execution contexts.
Similarly, the entry global object is the global object of the entry realm.
When Web IDL is used to invoke author code, or when HostEnqueuePromiseJob invokes a promise job, they use the following algorithms to track relevant data for determining the incumbent settings object:
Similarly, the incumbent global object is the global object of the incumbent settings object.
The following series of examples is intended to make it clear how all of the different mechanisms contribute to the definition of the incumbent concept:
The JavaScript specification defines the current realm, also known as the "current Realm Record". [JAVASCRIPT]
Similarly, the current global object is the global object of the current realm.
Similarly, the relevant global object for a platform object o is the global object of the relevant realm for o.
Scripting is disabled for an environment settings object when scripting is not enabled for it, i.e., when any of the above conditions are false.
Scripting is disabled for a node when scripting is not enabled, i.e., when its node document's browsing context is null or when scripting is disabled for its relevant settings object.
An environment is a non-secure context if it is not a secure context.
Module scripts can be classified into four types:
This section introduces a number of algorithms for fetching scripts, taking various necessary inputs and resulting in classic or module scripts.
Given a request request and a script fetch options options, we define:
Set request's cryptographic nonce metadata to options's cryptographic nonce, its integrity metadata to options's integrity metadata, its parser metadata to options's parser metadata, its referrer policy to options's referrer policy, its render-blocking to options's render-blocking, and its priority to options's fetch priority.
Set request's cryptographic nonce metadata to options's cryptographic nonce, its integrity metadata to options's integrity metadata, its parser metadata to options's parser metadata, its credentials mode to options's credentials mode, its referrer policy to options's referrer policy, its render-blocking to options's render-blocking, and its priority to options's fetch priority.
Several of the below algorithms can be customized with a perform the fetch
hook algorithm, which takes a request, a boolean isTopLevel, and a processCustomFetchResponse
algorithm. It runs processCustomFetchResponse with a response and either null (on failure) or a byte
sequence containing the response body. isTopLevel will be true for all classic
script fetches, and for the initial fetch when fetching an external module script graph or fetching a module worker script graph, but false for the fetches
resulting from import statements encountered throughout the graph or from
import() expressions.
By default, not supplying a perform the fetch hook will cause the below algorithms to simply fetch the given request, with algorithm-specific customizations to the request and validations of the resulting response.
To layer your own customizations on top of these algorithm-specific ones, supply a perform the fetch hook that modifies the given request, fetches it, and then performs specific validations of the resulting response (completing with a network error if the validations fail).
The hook can also be used to perform more subtle customizations, such as keeping a cache of responses and avoiding performing a fetch at all.
Now for the algorithms themselves.
The following algorithms are meant for internal use by this specification only as part of fetching an external module script graph or other similar concepts above, and should not be used directly by other specifications.
This diagram illustrates how these algorithms relate to the ones above, as well as to each other:
The running script is the script in the [[HostDefined]] field in the ScriptOrModule component of the running JavaScript execution context.
User agents may impose resource limitations on scripts, for example CPU quotas, memory limits,
total execution time limits, or bandwidth limitations. When a script exceeds a limit, the user
agent may either throw a "QuotaExceededError" DOMException,
abort the script without an exception, prompt the
user, or throttle script execution.
User agents are encouraged to allow users to disable scripting whenever the user is prompted
either by a script (e.g. using the window.alert() API) or because
of a script's actions (e.g. because it has exceeded a time limit).
If scripting is disabled while a script is executing, the script should be terminated immediately.
User agents may allow users to specifically disable scripts just for the purposes of closing a browsing context.
Support in all current engines.
To report an exception exception which is a JavaScript value, for a particular global object global and optional boolean omitError (default false):
Let notHandled be true.
Let errorInfo be the result of extracting error information from exception.
Let script be a script found in an implementation-defined way, or null. This should usually be the running script (most notably during run a classic script).
If script is a classic script and script's muted
errors is true, then set errorInfo[error] to null, errorInfo[message] to "Script error.",
errorInfo[filename] to the empty
string, errorInfo[lineno] to 0, and
errorInfo[colno] to 0.
If omitError is true, then set errorInfo[error] to null.
If global is not in error reporting mode, then:
If global implements EventTarget, then set notHandled to
the result of firing an event named error at global, using ErrorEvent, with
the cancelable attribute initialized to true,
and additional attributes initialized according to errorInfo.
Set global's in error reporting mode to false.
If notHandled is true, then:
Set errorInfo[error] to
null.
If global implements DedicatedWorkerGlobalScope, queue a
global task on the DOM manipulation task source with the
global's associated Worker's relevant global object to
run these steps:
Let workerObject be the Worker object associated with
global.
Set notHandled be the result of firing
an event named error at workerObject,
using ErrorEvent, with the cancelable attribute initialized to true,
and additional attributes initialized according to errorInfo.
If notHandled is true, then report exception for workerObject's relevant global object with omitError set to true.
Otherwise, the user agent may report exception to a developer console.
If the implicit port connecting a worker to its Worker object has been
disentangled (i.e. if the parent worker has been terminated), then the user agent must act as if
the Worker object had no error event handler and as
if that worker's onerror attribute was
null, but must otherwise act as described above.
Previous revisions of this standard defined an algorithm to report the exception. As part of issue #958, this has been superseded by report an exception which behaves differently and takes different inputs. Issue #10516 tracks updating the specification ecosystem.
The reportError(e) method steps are to
report an exception e for this.
Support in all current engines.
The ErrorEvent interface is defined as follows:
The error
attribute must return the value it was initialized to. It must initially be initialized to
undefined. Where appropriate, it is set to the object representing the error (e.g., the exception
object in the case of an uncaught exception).
Support in all current engines.
In addition to synchronous runtime script errors, scripts
may experience asynchronous promise rejections, tracked via the unhandledrejection and rejectionhandled events. Tracking these
rejections is done via the HostPromiseRejectionTracker abstract operation, but
reporting them is defined here.
Support in all current engines.
The PromiseRejectionEvent interface is
defined as follows:
Support in all current engines.
The promise attribute must return the value it
was initialized to. It represents the promise which this notification is about.
Support in all current engines.
The reason attribute must return the value it
was initialized to. It represents the rejection reason for the promise.
The resolve a module specifier algorithm is the primary entry point for converting module specifier strings into URLs. When no import maps are involved, it is relatively straightforward, and reduces to resolving a URL-like module specifier.
When there is a non-empty import map present, the behavior is more complex. It checks candidate entries from all applicable module specifier maps, from most-specific to least-specific scopes (falling back to the top-level unscoped imports), and from most-specific to least-specific prefixes. For each candidate, the resolve an imports match algorithm will give on the following results:
Successful resolution of the specifier to a URL. Then the resolve a module specifier algorithm will return that URL.
Throwing an exception. Then the resolve a module specifier algorithm will rethrow that exception, without any further fallbacks.
Failing to resolve, without an error. In this case the outer resolve a module specifier algorithm will move on to the next candidate.
In the end, if no successful resolution is found via any of the candidate module specifier maps, resolve a module specifier will throw an exception. Thus the result is always either a URL or a thrown exception.
An import map allows control over module specifier resolution. Import maps
are delivered via inline script elements with their type attribute set to "importmap", and
with their child text content containing a JSON representation of the import
map.
A Document can have multiple import maps processed, which can happen either
before or after any modules have been imported, e.g., via import() expressions or
script elements with their type attribute set
to "module". The merge existing and new import maps algorithm
ensures that new import maps cannot define the module resolution for modules that were already
defined by past import maps, or for ones that were already resolved.
An empty import map is an import map with its imports and scopes both being empty maps.
The above algorithm merges a new import map into the given environment settings object's global object's import map. Let's examine a few examples:
The JavaScript specification contains a number of implementation-defined abstract operations, that vary depending on the host environment. This section defines them for user agent hosts.
JavaScript contains an implementation-defined HostEnsureCanAddPrivateElement(O) abstract operation. User agents must use the following implementation: [JAVASCRIPT]
If O is a WindowProxy object, or implements
Location, then return Completion { [[Type]]: throw, [[Value]]: a new
TypeError }.
Return NormalCompletion(unused).
JavaScript contains an implementation-defined HostEnsureCanCompileStrings abstract operation, redefined by the Dynamic Code Brand Checks proposal. User agents must use the following implementation: [JAVASCRIPT] [JSDYNAMICCODEBRANDCHECKS]
Perform ? EnsureCSPDoesNotBlockStringCompilation(realm, parameterStrings, bodyString, codeString, compilationType, parameterArgs, bodyArg). [CSP]
The Dynamic Code Brand Checks proposal contains an implementation-defined HostGetCodeForEval(argument) abstract operation. User agents must use the following implementation: [JSDYNAMICCODEBRANDCHECKS]
If argument is a TrustedScript object,
then return argument's data.
Otherwise, return no-code.
JavaScript contains an implementation-defined HostPromiseRejectionTracker(promise, operation) abstract operation. User agents must use the following implementation: [JAVASCRIPT]
Let script be the running script.
If script is a classic script and script's muted errors is true, then return.
Let settingsObject be the current settings object.
If script is not null, then set settingsObject to script's settings object.
Let global be settingsObject's global object.
If operation is "reject", then:
Append promise to global's about-to-be-notified rejected promises list.
If operation is "handle", then:
If global's about-to-be-notified rejected promises list contains promise, then remove promise from that list and return.
If global's outstanding rejected promises weak set does not contain promise, then return.
Remove promise from global's outstanding rejected promises weak set.
Queue a global task on the DOM manipulation task source given
global to fire an event named rejectionhandled at global, using
PromiseRejectionEvent, with the promise attribute initialized to
promise, and the reason
attribute initialized to promise.[[PromiseResult]].
The Temporal proposal contains an implementation-defined HostSystemUTCEpochNanoseconds abstract operation. User agents must use the following implementation: [JSTEMPORAL]
Let settingsObject be global's relevant settings object.
Let time be settingsObject's current wall time.
Let ns be the number of nanoseconds from the Unix epoch to time, rounded to the nearest integer.
Return the result of clamping ns between nsMinInstant and nsMaxInstant.
Reference/Global_Objects/Promise#Incumbent_settings_object_tracking
Support in one engine only.
The JavaScript specification defines Jobs to be scheduled and run later by the host, as well as
JobCallback Records which encapsulate JavaScript
functions that are called as part of jobs. The JavaScript specification contains a number of
implementation-defined abstract operations that lets the host define how jobs are
scheduled and how JobCallbacks are handled. HTML uses these abstract operations to track the incumbent settings
object in promises and FinalizationRegistry callbacks by saving and
restoring the incumbent settings object and a JavaScript execution
context for the active script in JobCallbacks. This section defines them for
user agent hosts.
JavaScript contains an implementation-defined HostCallJobCallback(callback, V, argumentsList) abstract operation to let hosts restore state when invoking JavaScript callbacks from inside tasks. User agents must use the following implementation: [JAVASCRIPT]
Let incumbent settings be callback.[[HostDefined]].[[IncumbentSettings]].
Let script execution context be callback.[[HostDefined]].[[ActiveScriptContext]].
Prepare to run a callback with incumbent settings.
If script execution context is not null, then push script execution context onto the JavaScript execution context stack.
Let result be Call(callback.[[Callback]], V, argumentsList).
If script execution context is not null, then pop script execution context from the JavaScript execution context stack.
Clean up after running a callback with incumbent settings.
Return result.
JavaScript has the ability to register objects with FinalizationRegistry objects,
in order to schedule a cleanup action if they are found to be garbage collected. The JavaScript
specification contains an implementation-defined HostEnqueueFinalizationRegistryCleanupJob(finalizationRegistry)
abstract operation to schedule the cleanup action.
Cleanup actions do not take place interspersed with synchronous JavaScript execution, but rather happen in queued tasks. User agents must use the following implementation: [JAVASCRIPT]
Let global be finalizationRegistry.[[Realm]]'s global object.
JavaScript contains an implementation-defined HostEnqueueGenericJob(job, realm)
abstract operation to perform generic jobs in a particular realm (e.g., resolve promises resulting
from Atomics.waitAsync). User agents must use the following implementation:
[JAVASCRIPT]
Let global be realm's global object.
Queue a global task on the JavaScript engine task source given global to perform job().
JavaScript contains an implementation-defined HostEnqueuePromiseJob(job, realm) abstract operation to schedule Promise-related operations. HTML schedules these operations in the microtask queue. User agents must use the following implementation: [JAVASCRIPT]
If realm is not null, then let job settings be the settings object for realm. Otherwise, let job settings be null.
Queue a microtask to perform the following steps:
If job settings is not null, then check if we can run script with job settings. If this returns "do not run" then return.
If job settings is not null, then prepare to run script with job settings.
Let result be job().
If job settings is not null, then clean up after running script with job settings.
If result is an abrupt completion, then report an exception given by result.[[Value]] for realm's global object.
JavaScript contains an implementation-defined HostEnqueueTimeoutJob(job, milliseconds) abstract operation to schedule an operation to be performed after a timeout. HTML schedules these operations using run steps after a timeout. User agents must use the following implementation: [JAVASCRIPT]
Let global be realm's global object.
Let timeoutStep be an algorithm step which queues a global task on the JavaScript engine task source given global to perform job().
Run steps after a timeout given global, "JavaScript", milliseconds, and timeoutStep.
JavaScript contains an implementation-defined HostMakeJobCallback(callable) abstract operation to let hosts attach state to JavaScript callbacks that are called from inside tasks. User agents must use the following implementation: [JAVASCRIPT]
Let incumbent settings be the incumbent settings object.
Let active script be the active script.
Let script execution context be null.
If active script is not null, set script execution context to a new JavaScript execution context, with its Function field set to null, its Realm field set to active script's settings object's realm, and its ScriptOrModule set to active script's record.
Return the JobCallback Record { [[Callback]]: callable, [[HostDefined]]: { [[IncumbentSettings]]: incumbent settings, [[ActiveScriptContext]]: script execution context } }.
The JavaScript specification defines a syntax for modules, as well as some host-agnostic parts
of their processing model. This specification defines the rest of their processing model: how the
module system is bootstrapped, via the script element with type attribute set to "module", and how
modules are fetched, resolved, and executed. [JAVASCRIPT]
A module map is a map keyed by tuples consisting of a URL record and a string.
The URL record is the request URL at which
the module was fetched, and the string indicates the type of the module (e.g. "javascript-or-wasm"). The module map's values are either a
module script, null (used to represent failed fetches), or a placeholder value "fetching". Module maps are used to ensure
that imported module scripts are only fetched, parsed, and evaluated once per
Document or worker.
Reference/Operators/import.meta/resolve
Support in all current engines.
Reference/Operators/import.meta
Support in all current engines.
JavaScript contains an implementation-defined HostGetImportMetaProperties abstract operation. User agents must use the following implementation: [JAVASCRIPT]
Let moduleScript be moduleRecord.[[HostDefined]].
Assert: moduleScript's base URL is not null, as moduleScript is a JavaScript module script.
Let urlString be moduleScript's base URL, serialized.
Let steps be the following steps, given the argument specifier:
Set specifier to ? ToString(specifier).
Let url be the result of resolving a module specifier given moduleScript and specifier.
Return the serialization of url.
Let resolveFunction be ! CreateBuiltinFunction(steps,
1, "resolve", « »).
Return « Record { [[Key]]: "url", [[Value]]: urlString },
Record { [[Key]]: "resolve",
[[Value]]: resolveFunction } ».
The Import Attributes proposal contains an implementation-defined HostGetSupportedImportAttributes abstract operation. User agents must use the following implementation: [JSIMPORTATTRIBUTES]
Return « "type" ».
JavaScript contains an implementation-defined HostLoadImportedModule abstract operation. User agents must use the following implementation: [JAVASCRIPT]
Let settingsObject be the current settings object.
If settingsObject's global
object implements WorkletGlobalScope or ServiceWorkerGlobalScope
and loadState is undefined, then:
Let completion be Completion Record { [[Type]]: throw,
[[Value]]: a new TypeError, [[Target]]: empty }.
Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, completion).
Return.
Let referencingScript be null.
Let originalFetchOptions be the default script fetch options.
Let fetchReferrer be "client".
If referrer is a Script Record or a Cyclic Module Record, then:
Set referencingScript to referrer.[[HostDefined]].
Set settingsObject to referencingScript's settings object.
Set fetchReferrer to referencingScript's base URL.
Set originalFetchOptions to referencingScript's fetch options.
If referrer is a Cyclic Module Record and moduleRequest is equal to the first element of referrer.[[RequestedModules]], then:
For each ModuleRequest record requested of referrer.[[RequestedModules]]:
If moduleRequest.[[Attributes]] contains a Record entry
such that entry.[[Key]] is not "type", then:
Let completion be Completion Record { [[Type]]: throw,
[[Value]]: a new SyntaxError exception, [[Target]]: empty }.
Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, completion).
Return.
Resolve a module specifier given referencingScript and moduleRequest.[[Specifier]], catching any exceptions. If they throw an exception, let resolutionError be the thrown exception.
If the previous step threw an exception, then:
Let completion be Completion Record { [[Type]]: throw, [[Value]]: resolutionError, [[Target]]: empty }.
Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, completion).
Return.
Let moduleType be the result of running the module type from module request steps given moduleRequest.
If the result of running the module type allowed steps given moduleType and settingsObject is false, then:
Let completion be Completion Record { [[Type]]: throw,
[[Value]]: a new TypeError exception, [[Target]]: empty }.
Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, completion).
Return.
Let url be the result of resolving a module specifier given referencingScript and moduleRequest.[[Specifier]], catching any exceptions. If they throw an exception, let resolutionError be the thrown exception.
If the previous step threw an exception, then:
Let completion be Completion Record { [[Type]]: throw, [[Value]]: resolutionError, [[Target]]: empty }.
Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, completion).
Return.
Let fetchOptions be the result of getting the descendant script fetch options given originalFetchOptions, url, and settingsObject.
Let destination be "script".
Let fetchClient be settingsObject.
If loadState is not undefined, then:
Set destination to loadState.[[Destination]].
Set fetchClient to loadState.[[FetchClient]].
Fetch a single imported module script given url, fetchClient, destination, fetchOptions, settingsObject, fetchReferrer, moduleRequest, and onSingleFetchComplete as defined below. If loadState is not undefined and loadState.[[PerformFetch]] is not null, pass loadState.[[PerformFetch]] along as well.
onSingleFetchComplete given moduleScript is the following algorithm:
Let completion be null.
If moduleScript is null, then set completion to Completion
Record { [[Type]]: throw, [[Value]]: a new TypeError, [[Target]]: empty
}.
Otherwise, if moduleScript's parse error is not null, then:
Let parseError be moduleScript's parse error.
Set completion to Completion Record { [[Type]]: throw, [[Value]]: parseError, [[Target]]: empty }.
If loadState is not undefined and loadState.[[ParseError]] is null, set loadState.[[ParseError]] to parseError.
Otherwise, set completion to Completion Record { [[Type]]: normal, [[Value]]: moduleScript's record, [[Target]]: empty }.
Perform FinishLoadingImportedModule(referrer, moduleRequest, payload, completion).
The event loop of a similar-origin window agent is known as a window event loop. The event loop of a dedicated worker agent, shared worker agent, or service worker agent is known as a worker event loop. And the event loop of a worklet agent is known as a worklet event loop.
Tasks encapsulate algorithms that are responsible for such work as:
Dispatching an Event object at a particular
EventTarget object is often done by a dedicated task.
The HTML parser tokenizing one or more bytes, and then processing any resulting tokens, is typically a task.
Calling a callback is often done by a dedicated task.
When an algorithm fetches a resource, if the fetching occurs in a non-blocking fashion then the processing of the resource once some or all of the resource is available is performed by a task.
Some elements have tasks that trigger in response to DOM manipulation, e.g. when that element is inserted into the document.
Per its source field, each task is defined as coming from a specific task source. For each event loop, every task source must be associated with a specific task queue.
Each event loop has a microtask queue, which is a queue of microtasks, initially empty. A microtask is a colloquial way of referring to a task that was created via the queue a microtask algorithm.
To get the same-loop windows for a window event loop loop,
return all Window objects whose relevant agent's
event loop is loop.
An event loop must continually run through the following steps for as long as it exists:
Let oldestTask and taskStartTime be null.
If the event loop has a task queue with at least one runnable task, then:
Let taskQueue be one such task queue, chosen in an implementation-defined manner.
Set taskStartTime to the unsafe shared current time.
Set oldestTask to the first runnable task in taskQueue, and remove it from taskQueue.
If oldestTask's document is not null, then record task start time given taskStartTime and oldestTask's document.
Set the event loop's currently running task to oldestTask.
Perform oldestTask's steps.
Set the event loop's currently running task back to null.
Let taskEndTime be the unsafe shared current time. [HRT]
If oldestTask is not null, then:
Let top-level browsing contexts be an empty set.
For each environment settings object settings of oldestTask's script evaluation environment settings object set:
Let global be settings's global object.
If global's browsing context is null, then continue.
Let tlbc be global's browsing context's top-level browsing context.
If tlbc is not null, then append it to top-level browsing contexts.
Report long tasks, passing in taskStartTime, taskEndTime, top-level browsing contexts, and oldestTask.
If oldestTask's document is not null, then record task end time given taskEndTime and oldestTask's document.
If this is a window event loop that has no runnable task in this event loop's task queues, then:
Set this event loop's last idle period start time to the unsafe shared current time.
Let computeDeadline be the following steps:
Let deadline be this event loop's last idle period start time plus 50.
Let hasPendingRenders be false.
For each windowInSameLoop of the same-loop windows for this event loop:
If windowInSameLoop's map of animation frame callbacks is not empty, or if the user agent believes that the windowInSameLoop might have pending rendering updates, set hasPendingRenders to true.
Let timerCallbackEstimates be the result of getting the values of windowInSameLoop's map of active timers.
For each timeoutDeadline of timerCallbackEstimates, if timeoutDeadline is less than deadline, set deadline to timeoutDeadline.
If hasPendingRenders is true, then:
Let nextRenderDeadline be this event loop's last render opportunity time plus (1000 divided by the current refresh rate).
The refresh rate can be hardware- or implementation-specific. For a refresh rate of 60Hz, the nextRenderDeadline would be about 16.67ms after the last render opportunity time.
If nextRenderDeadline is less than deadline, then return nextRenderDeadline.
Return deadline.
For each win of the same-loop windows for this event loop, perform the start an idle period algorithm for win with the following step: return the result of calling computeDeadline, coarsened given win's relevant settings object's cross-origin isolated capability. [REQUESTIDLECALLBACK]
If this is a worker event loop, then:
If this event loop's agent's single realm's global object is a supported
DedicatedWorkerGlobalScope and the user agent believes that it would benefit
from having its rendering updated at this time, then:
Let now be the current high resolution time given the
DedicatedWorkerGlobalScope. [HRT]
Run the animation frame callbacks for that
DedicatedWorkerGlobalScope, passing in now as the
timestamp.
Update the rendering of that dedicated worker to reflect the current state.
If there are no tasks in the event
loop's task queues and the
WorkerGlobalScope object's closing flag is true, then destroy the
event loop, aborting these steps, resuming the run a worker steps
described in the Web workers section below.
A window event loop eventLoop must also run the following in parallel, as long as it exists:
Wait until at least one navigable whose active document's relevant agent's event loop is eventLoop might have a rendering opportunity.
Set eventLoop's last render opportunity time to the unsafe shared current time.
A navigable's rendering opportunities
are determined based on hardware constraints such as display refresh rates and other factors such
as page performance or whether its active document's
visibility state is "visible". Rendering opportunities
typically occur at regular intervals.
The following task sources are used by a number of mostly unrelated features in this and other specifications.
This task source is used for features that react to DOM manipulations, such as things that happen in a non-blocking fashion when an element is inserted into the document.
This task source is used for features that react to user interaction, for example keyboard or mouse input.
Events sent in response to user input (e.g. click events) must be fired using tasks queued with the user
interaction task source. [UIEVENTS]
This task source is used for features that trigger in response to network activity.
This task source is used to queue tasks involved in navigation and history traversal.
This task source is used solely to update the rendering.
Writing specifications that correctly interact with the event loop can be tricky. This is compounded by how this specification uses concurrency-model-independent terminology, so we say things like "event loop" and "in parallel" instead of using more familiar model-specific terms like "main thread" or "on a background thread".
By default, specification text generally runs on the event loop. This falls out from the formal event loop processing model, in that you can eventually trace most algorithms back to a task queued there.
From this starting point, the overriding guideline is that any work a specification needs to perform that would otherwise block the event loop must instead be performed in parallel with it. This includes (but is not limited to):
performing heavy computation;
displaying a user-facing prompt;
performing operations which could require involving outside systems (i.e. "going out of process").
The next complication is that, in algorithm sections that are in parallel, you must not create or manipulate objects associated to a specific realm, global, or environment settings object. (Stated in more familiar terms, you must not directly access main-thread artifacts from a background thread.) Doing so would create data races observable to JavaScript code, since after all, your algorithm steps are running in parallel to the JavaScript code.
You can, however, manipulate specification-level data structures and values from Infra, as those are realm-agnostic. They are never directly exposed to JavaScript without a specific conversion taking place (often via Web IDL). [INFRA] [WEBIDL]
To affect the world of observable JavaScript objects, then, you must queue a global task to perform any such manipulations. This ensures your steps are properly interleaved with respect to other things happening on the event loop. Furthermore, you must choose a task source when queuing a global task; this governs the relative order of your steps versus others. If you are unsure which task source to use, pick one of the generic task sources that sounds most applicable. Finally, you must indicate which global object your queued task is associated with; this ensures that if that global object is inactive, the task does not run.
Putting this all together, we can provide a template for a typical algorithm that needs to do work asynchronously:
Do any synchronous setup work, while still on the event loop. This may include converting realm-specific JavaScript values into realm-agnostic specification-level values.
Perform a set of potentially-expensive steps in parallel, operating entirely on realm-agnostic values, and producing a realm-agnostic result.
Queue a global task, on a specified task source and given an appropriate global object, to convert the realm-agnostic result back into observable effects on the observable world of JavaScript objects on the event loop.
An event handler is a struct with two items:
Event handlers are exposed in two ways.
The first way, common to all event handlers, is as an event handler IDL attribute.
The second way is as an event handler content
attribute. Event handlers on HTML elements and some of the event handlers on
Window objects are exposed in this way.
For both of these two ways, the event handler is exposed
through a name, which is a string that always starts with
"on" and is followed by the name of the event for which the handler is
intended.
When an EventTarget object that has one or more event handlers
specified is created, its event handler map must be initialized such that it contains
an entry for each event
handler that has that object as target, with
items in those event handlers set to their initial
values.
The getter of an event handler IDL attribute with name name, when called, must run these steps:
Let eventTarget be the result of determining the target of an event handler given this object and name.
If eventTarget is null, then return null.
Return the result of getting the current value of the event handler given eventTarget and name.
The setter of an event handler IDL attribute with name name, when called, must run these steps:
Let eventTarget be the result of determining the target of an event handler given this object and name.
If eventTarget is null, then return.
If the given value is null, then deactivate an event handler given eventTarget and name.
Otherwise:
Let handlerMap be eventTarget's event handler map.
Let eventHandler be handlerMap[name].
Set eventHandler's value to the given value.
Activate an event handler given eventTarget and name.
Event handler content attributes, when specified, must contain valid JavaScript code which, when parsed, would match the FunctionBody production after automatic semicolon insertion.
The following attribute change steps are used to synchronize between event handler content attributes and event handlers: [DOM]
If namespace is not null, or localName is not the name of an event handler content attribute on element, then return.
Let eventTarget be the result of determining the target of an event handler given element and localName.
If eventTarget is null, then return.
If value is null, then deactivate an event handler given eventTarget and localName.
Otherwise:
If the Should element's inline behavior be blocked by Content Security
Policy? algorithm returns "Blocked" when executed upon
element, "script attribute", and value, then
return. [CSP]
Let handlerMap be eventTarget's event handler map.
Let eventHandler be handlerMap[localName].
Let location be the script location that triggered the execution of these steps.
Set eventHandler's value to the internal raw uncompiled handler value/location.
Activate an event handler given eventTarget and localName.
The EventHandler callback function type represents a callback used for event
handlers. It is represented in Web IDL as follows:
For historical reasons, the onerror handler has different
arguments:
Similarly, the onbeforeunload handler has a
different return value:
Document objects, and Window objectsThe following are the event handlers (and their corresponding event handler event types) that must be
supported by all HTML elements, as both event handler content attributes
and event handler IDL attributes; and that must be
supported by all Document and Window objects, as event handler IDL
attributes:
| Event handler | Event handler event type |
|---|---|
onabort Support in all current engines. Firefox9+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | abort
|
onauxclick Firefox53+SafariNoChrome55+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android53+Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | auxclick
|
onbeforeinput | beforeinput
|
onbeforematch | beforematch
|
onbeforetoggle | beforetoggle
|
oncancel HTMLDialogElement/cancel_event Support in all current engines. Firefox98+Safari15.4+Chrome37+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome AndroidNoWebView Android?Samsung Internet?Opera Android? | cancel
|
oncanplay HTMLMediaElement/canplay_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | canplay
|
oncanplaythrough HTMLMediaElement/canplaythrough_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | canplaythrough
|
onchange Support in all current engines. Firefox1+Safari3+Chrome1+ Opera9+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | change
|
onclick Support in all current engines. Firefox6+Safari3+Chrome1+ Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android6+Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | click
|
onclose | close
|
oncontextlost | contextlost
|
oncontextmenu | contextmenu
|
oncontextrestored | contextrestored
|
oncopy Support in all current engines. Firefox22+Safari3+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | copy
|
oncuechange HTMLTrackElement/cuechange_event Support in all current engines. Firefox68+Safari10+Chrome32+ Opera19+Edge79+ Edge (Legacy)14+Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android4.4.3+Samsung Internet?Opera Android19+ | cuechange
|
oncut Support in all current engines. Firefox22+Safari3+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | cut
|
ondblclick Support in all current engines. Firefox6+Safari3+Chrome1+ Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer8+ Firefox Android6+Safari iOS1+Chrome AndroidNoWebView Android?Samsung Internet?Opera Android12.1+ | dblclick
|
ondrag | drag
|
ondragend | dragend
|
ondragenter | dragenter
|
ondragleave | dragleave
|
ondragover | dragover
|
ondragstart | dragstart
|
ondrop | drop
|
ondurationchange HTMLMediaElement/durationchange_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | durationchange
|
onemptied HTMLMediaElement/emptied_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | emptied
|
onended Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | ended
|
onformdata | formdata
|
oninput Support in all current engines. Firefox6+Safari3.1+Chrome1+ Opera11.6+Edge79+ Edge (Legacy)NoInternet Explorer🔰 9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | input
|
oninvalid | invalid
|
onkeydown Support in all current engines. Firefox6+Safari1.2+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | keydown
|
onkeypress | keypress
|
onkeyup Support in all current engines. Firefox6+Safari1.2+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | keyup
|
onloadeddata HTMLMediaElement/loadeddata_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | loadeddata
|
onloadedmetadata HTMLMediaElement/loadedmetadata_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | loadedmetadata
|
onloadstart HTMLMediaElement/loadstart_event Support in all current engines. Firefox6+Safari4+Chrome3+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | loadstart
|
onmousedown Support in all current engines. Firefox6+Safari4+Chrome2+ Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | mousedown
|
onmouseenter Support in all current engines. Firefox10+Safari7+Chrome30+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer5.5+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | mouseenter
|
onmouseleave Support in all current engines. Firefox10+Safari7+Chrome30+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer5.5+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | mouseleave
|
onmousemove Support in all current engines. Firefox6+Safari4+Chrome2+ Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | mousemove
|
onmouseout Support in all current engines. Firefox6+Safari1+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | mouseout
|
onmouseover Support in all current engines. Firefox6+Safari4+Chrome2+ Opera9.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android10.1+ | mouseover
|
onmouseup Support in all current engines. Firefox6+Safari4+Chrome2+ Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | mouseup
|
onpaste Support in all current engines. Firefox22+Safari3+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | paste
|
onpause Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | pause
|
onplay Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | play
|
onplaying HTMLMediaElement/playing_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | playing
|
onprogress HTMLMediaElement/progress_event Support in all current engines. Firefox6+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | progress
|
onratechange HTMLMediaElement/ratechange_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | ratechange
|
onreset | reset
|
onscrollend Firefox109+SafariNoChrome114+ Opera?Edge114+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? Firefox109+SafariNoChrome114+ Opera?Edge114+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | scrollend
|
onsecuritypolicyviolation Element/securitypolicyviolation_event Support in all current engines. Firefox63+Safari10+Chrome41+ Opera?Edge79+ Edge (Legacy)15+Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | securitypolicyviolation
|
onseeked Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | seeked
|
onseeking HTMLMediaElement/seeking_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | seeking
|
onselect Support in all current engines. Firefox6+Safari1+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ HTMLTextAreaElement/select_event Support in all current engines. Firefox6+Safari1+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | select
|
onslotchange HTMLSlotElement/slotchange_event Support in all current engines. Firefox63+Safari10.1+Chrome53+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | slotchange
|
onstalled HTMLMediaElement/stalled_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | stalled
|
onsubmit Support in all current engines. Firefox1+Safari3+Chrome1+ Opera8+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | submit
|
onsuspend HTMLMediaElement/suspend_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | suspend
|
ontimeupdate HTMLMediaElement/timeupdate_event Support in all current engines. Firefox3.5+Safari3.1+Chrome3+ Opera10.5+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | timeupdate
|
ontoggle | toggle
|
onvolumechange HTMLMediaElement/volumechange_event Support in all current engines. Firefox6+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | volumechange
|
onwaiting HTMLMediaElement/waiting_event Support in all current engines. Firefox6+Safari3.1+Chrome3+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | waiting
|
onwebkitanimationend | webkitAnimationEnd
|
onwebkitanimationiteration | webkitAnimationIteration
|
onwebkitanimationstart | webkitAnimationStart
|
onwebkittransitionend | webkitTransitionEnd
|
onwheel Support in all current engines. Firefox17+Safari7+Chrome31+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOSNoChrome Android?WebView Android?Samsung Internet?Opera Android? | wheel
|
The following are the event handlers (and their corresponding event handler event types) that must be
supported by all HTML elements other than body and frameset
elements, as both event handler content attributes and event handler IDL
attributes; that must be supported by all Document
objects, as event handler IDL attributes; and that must be
supported by all Window objects, as event handler IDL attributes on the
Window objects themselves, and with corresponding event handler content
attributes and event handler IDL attributes exposed on all body
and frameset elements that are owned by that Window object's associated Document:
| Event handler | Event handler event type |
|---|---|
onblur Support in all current engines. Firefox24+Safari3.1+Chrome1+ Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ Support in all current engines. Firefox6+Safari5.1+Chrome5+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | blur
|
onerror Support in all current engines. Firefox6+Safari5.1+Chrome10+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | error
|
onfocus Support in all current engines. Firefox24+Safari3.1+Chrome1+ Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ Support in all current engines. Firefox6+Safari5.1+Chrome5+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | focus
|
onload | load
|
onresize | resize
|
onscroll Support in all current engines. Firefox6+Safari2+Chrome1+ Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12+ Support in all current engines. Firefox6+Safari1.3+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | scroll
|
We call the set of the names of the
event handlers listed in the first column of this table the
Window-reflecting body element event handler set.
The following are the event handlers (and their corresponding event handler event types) that must be
supported by Window objects, as event handler IDL attributes on the
Window objects themselves, and with corresponding event handler content
attributes and event handler IDL attributes exposed on all body
and frameset elements that are owned by that Window object's associated Document:
| Event handler | Event handler event type |
|---|---|
onafterprint Support in all current engines. Firefox6+Safari13+Chrome63+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | afterprint
|
onbeforeprint Support in all current engines. Firefox6+Safari13+Chrome63+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | beforeprint
|
onbeforeunload Support in all current engines. Firefox1+Safari3+Chrome1+ Opera12+Edge79+ Edge (Legacy)12+Internet Explorer4+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | beforeunload
|
onhashchange Support in all current engines. Firefox3.6+Safari5+Chrome8+ Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer8+ Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | hashchange
|
onlanguagechange Support in all current engines. Firefox32+Safari10.1+Chrome37+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android4+Safari iOS?Chrome Android?WebView Android?Samsung Internet4.0+Opera Android? | languagechange
|
onmessage Support in all current engines. Firefox9+Safari4+Chrome60+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer8+ Firefox Android?Safari iOS4+Chrome Android?WebView Android?Samsung Internet?Opera Android47+ | message
|
onmessageerror Support in all current engines. Firefox6+Safari3.1+Chrome3+ Opera11.6+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ Support in all current engines. Firefox57+Safari16.4+Chrome60+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ | messageerror
|
onoffline Support in all current engines. Firefox9+Safari4+Chrome3+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | offline
|
ononline Support in all current engines. Firefox9+Safari4+Chrome3+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | online
|
onpageswap | pageswap
|
onpagehide | pagehide
|
onpagereveal | pagereveal
|
onpageshow | pageshow
|
onpopstate Support in all current engines. Firefox4+Safari5+Chrome5+ Opera11.5+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ | popstate
|
onrejectionhandled Support in all current engines. Firefox69+Safari11+Chrome49+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS11.3+Chrome Android?WebView Android?Samsung Internet?Opera Android? | rejectionhandled
|
onstorage Support in all current engines. Firefox45+Safari4+Chrome1+ Opera?Edge79+ Edge (Legacy)15+Internet Explorer9+ Firefox Android?Safari iOS4+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | storage
|
onunhandledrejection Window/unhandledrejection_event Support in all current engines. Firefox69+Safari11+Chrome49+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS11.3+Chrome Android?WebView Android?Samsung Internet?Opera Android? | unhandledrejection
|
onunload Support in all current engines. Firefox1+Safari3+Chrome1+ Opera4+Edge79+ Edge (Legacy)12+Internet Explorer4+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | unload
|
This list of event handlers is reified as event handler IDL
attributes through the WindowEventHandlers interface mixin.
The following are the event handlers (and their corresponding event handler event types) that must be
supported on Document objects as event handler IDL attributes:
| Event handler | Event handler event type |
|---|---|
onreadystatechange | readystatechange
|
onvisibilitychange Document/visibilitychange_event Support in all current engines. Firefox56+Safari14.1+Chrome62+ Opera49+Edge79+ Edge (Legacy)18Internet Explorer🔰 10+ Firefox Android?Safari iOS?Chrome Android?WebView Android62+Samsung Internet?Opera Android46+ | visibilitychange
|
Certain operations and methods are defined as firing events on elements. For example, the click() method on the HTMLElement interface is defined as
firing a click event on the element. [UIEVENTS]
Firing a click event
at target means firing a synthetic
pointer event named click at target.
WindowOrWorkerGlobalScope mixinThe WindowOrWorkerGlobalScope mixin is for use of APIs that are to be exposed on
Window and WorkerGlobalScope objects.
The crossOriginIsolated getter steps are to return
this's relevant settings object's cross-origin isolated
capability.
The atob() and btoa() methods
allow developers to transform content to and from the base64 encoding.
Document objects have a throw-on-dynamic-markup-insertion counter,
which is used in conjunction with the create an element for the token algorithm to
prevent custom element constructors from being
able to use document.open(), document.close(), and document.write() when they are invoked by the parser.
Initially, the counter must be set to zero.
document.write()The document.write(...text) method steps are
to run the document write steps with this, text, false, and
"Document write".
document.writeln()The document.writeln(...text) method steps are
to run the document write steps with this, text, true, and
"Document writeln".
Support in all current engines.
DOMParser interfaceThe DOMParser interface allows authors to create new Document objects
by parsing strings, as either HTML or XML.
ShadowRoot's getHTML(options) method steps
are to return the result of HTML fragment serialization algorithm with
this, options["serializableShadowRoots"],
and options["shadowRoots"].
innerHTML propertyElement's innerHTML setter steps
are:
Let compliantString be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, the given value, "Element innerHTML", and "script".
Let context be this.
Let fragment be the result of invoking the fragment parsing algorithm steps with context and compliantString.
If context is a template element, then set context to
the template element's template contents (a
DocumentFragment).
Replace all with fragment within context.
ShadowRoot's innerHTML setter
steps are:
Let compliantString be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, the given value, "ShadowRoot innerHTML", and "script".
Let fragment be the result of invoking the fragment parsing algorithm steps with context and compliantString.
Replace all with fragment within this.
outerHTML propertyElement's outerHTML setter steps
are:
Let compliantString be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, the given value, "Element outerHTML", and "script".
If parent is null, return. There would be no way to obtain a reference to the nodes created even if the remaining steps were run.
If parent is a Document, throw a
"NoModificationAllowedError" DOMException.
If parent is a DocumentFragment, set parent to the
result of creating an element given this's
node document, "body", and the HTML
namespace.
Let fragment be the result of invoking the fragment parsing algorithm steps given parent and compliantString.
insertAdjacentHTML() methodcreateContextualFragment()
methodThe setTimeout() and setInterval() methods allow authors to schedule timer-based
callbacks.
Objects that implement the WindowOrWorkerGlobalScope mixin have a
map of setTimeout and setInterval IDs, which is
an ordered map, initially empty. Each key in this map
is a positive integer, corresponding to the return value of a setTimeout() or setInterval() call.
Each value is a unique internal value, corresponding
to a key in the object's map of active timers.
The clearTimeout(id) and clearInterval(id) method steps
are to remove this's map of setTimeout and
setInterval IDs[id].
Support in all current engines.
The queueMicrotask() method allows authors to schedule
a callback on the microtask queue. This allows their code to run once the
JavaScript execution context stack is next empty, which happens once all currently
executing synchronous JavaScript has run to completion. This doesn't yield control back to the
event loop, as would be the case when using, for example, setTimeout(f, 0).
Authors ought to be aware that scheduling a lot of microtasks has the same performance
downsides as running a lot of synchronous code. Both will prevent the browser from doing its own
work, such as rendering. In many cases, requestAnimationFrame() or
requestIdleCallback() is a better choice. In particular, if the goal is to run code
before the next rendering cycle, that is the purpose of requestAnimationFrame().
As can be seen from the following examples, the best way of thinking about queueMicrotask() is as a mechanism for rearranging synchronous
code, effectively placing the queued code immediately after the currently executing synchronous
JavaScript has run to completion.
Support in all current engines.
User agents should also run the printing steps whenever the user asks for the opportunity to obtain a physical form (e.g. printed copy), or the representation of a physical form (e.g. PDF copy), of a document.
Navigator objectSupport in all current engines.
Instances of Navigator represent the identity and state of the user agent (the
client). It has also been used as a generic global under which various APIs are located, but this
is not precedent to build upon. Instead use the WindowOrWorkerGlobalScope mixin or
equivalent.
Each Window has an associated Navigator, which is a Navigator
object. Upon creation of the Window object, its associated Navigator must be
set to a new Navigator object created in the Window object's relevant realm.
Support in all current engines.
The navigator and clientInformation getter steps are to return
this's associated Navigator.
In certain cases, despite the best efforts of the entire industry, web browsers have bugs and limitations that web authors are forced to work around.
This section defines a collection of attributes that can be used to determine, from script, the kind of user agent in use, in order to work around these issues.
Client detection should always be limited to detecting known current versions; future versions and unknown versions should always be assumed to be fully compliant.
appCodeNameMust return the string "Mozilla".
appNameMust return the string "Netscape".
appVersionMust return the appropriate string that starts with "5.0 (", as
follows:
Let trail be the substring of default
`User-Agent` value that follows the "Mozilla/"
prefix.
Return trail.
If trail starts with "5.0 (Windows", then return "5.0 (Windows)".
Otherwise, return the prefix of trail up to but not including the first U+003B
(;), concatenated with the character U+0029 RIGHT PARENTHESIS. For example, "5.0 (Macintosh)", "5.0 (Android 10)", or "5.0 (X11)".
platformMust return a string representing the platform on which the
browser is executing (e.g. "MacIntel", "Win32",
"Linux x86_64", "Linux armv81") or, for privacy and
compatibility, a string that is commonly returned on another platform.
productMust return the string "Gecko".
productSubMust return the appropriate string from the following list:
The string "20030107".
The string "20100101".
userAgentMust return the default `User-Agent`
value.
vendorMust return the appropriate string from the following list:
The string "Google Inc.".
The empty string.
The string "Apple Computer, Inc.".
vendorSubMust return the empty string.
If the navigator compatibility mode is Gecko, then the user agent must also support the following partial interface:
The oscpu attribute's getter must return
either the empty string or a string representing the platform on which the browser is executing,
e.g. "Windows NT 10.0; Win64; x64", "Linux
x86_64".
languageMust return a valid BCP 47 language tag representing either a plausible language or the user's most preferred language. [BCP47]
languagesMust return a frozen array of valid BCP 47 language tags representing either one or more plausible languages, or the user's preferred languages, ordered by preference with the most preferred language first. The same object must be returned until the user agent needs to return different values, or values in a different order. [BCP47]
Whenever the user agent needs to make the navigator.languages attribute of a Window
or WorkerGlobalScope object global return a new set of language tags,
the user agent must queue a global task on the DOM manipulation task
source given global to fire an event
named languagechange at global, and wait
until that task begins to be executed before actually returning a new value.
To avoid introducing any more fingerprinting vectors, user agents should use the same list for the
APIs defined in this function as for the HTTP `
Accept-Language` header.
When the value that would be returned by the navigator.onLine attribute of a Window or
WorkerGlobalScope global changes from true to false, the user agent must
queue a global task on the networking task source given
global to fire an event named offline at global.
On the other hand, when the value that would be returned by the navigator.onLine attribute of a Window or
WorkerGlobalScope global changes from false to true, the user agent must
queue a global task on the networking task source given
global to fire an event named online at the Window or WorkerGlobalScope
object.
registerProtocolHandler() methodNavigator/registerProtocolHandler
Custom scheme handlers can introduce a number of concerns, in particular privacy concerns.
Hijacking all web usage. User agents should not allow schemes that are key to its normal operation, such as an HTTP(S) scheme, to be rerouted through third-party sites. This would allow a user's activities to be trivially tracked, and would allow user information, even in secure connections, to be collected.
Hijacking defaults. User agents are strongly urged to not automatically change any defaults, as this could lead the user to send data to remote hosts that the user is not expecting. New handlers registering themselves should never automatically cause those sites to be used.
Registration spamming. User agents should consider the possibility that a site
will attempt to register a large number of handlers, possibly from multiple domains (e.g., by
redirecting through a series of pages each on a different domain, and each registering a handler
for web+spam: — analogous practices abusing other web browser
features have been used by pornography web sites for many years). User agents should gracefully
handle such hostile attempts, protecting the user.
Hostile handler metadata. User agents should protect against typical attacks against strings embedded in their interface, for example ensuring that markup or escape characters in such strings are not executed, that null bytes are properly handled, that over-long strings do not cause crashes or buffer overruns, and so forth.
Leaking private data. Web page authors may reference a custom scheme handler using URL data considered private. They might do so with the expectation that the user's choice of handler points to a page inside the organization, ensuring that sensitive data will not be exposed to third parties. However, a user may have registered a handler pointing to an external site, resulting in a data leak to that third party. Implementers might wish to consider allowing administrators to disable custom handlers on certain subdomains, content types, or schemes.
Interface interference. User agents should be prepared to handle intentionally long arguments to the methods. For example, if the user interface exposed consists of an "accept" button and a "deny" button, with the "accept" binding containing the name of the handler, it's important that a long name not cause the "deny" button to be pushed off the screen.
For the purposes of user agent automation and website testing, this standard defines Set RPH Registration Mode WebDriver extension
command. It instructs the user agent to place a Document into a mode where it
will automatically simulate a user either accepting or rejecting and registration confirmation
prompt dialog.
| HTTP Method | URI Template |
|---|---|
`POST`
| /session/{session id}/custom-handlers/set-mode
|
The remote end steps are:
If parameters is not a JSON Object, return a WebDriver error with WebDriver error code invalid argument.
Let mode be the result of getting a property named "mode" from parameters.
If mode is not "autoAccept", "autoReject", or "none", return a WebDriver error with
WebDriver error code invalid argument.
Let document be the current browsing context's active document.
Set document's registerProtocolHandler() automation
mode to mode.
Return success with data null.
The cookieEnabled attribute must return true if the
user agent attempts to handle cookies according to HTTP State Management Mechanism,
and false if it ignores cookie change requests. [COOKIES]
Although these days detecting PDF viewer support can be done via navigator.pdfViewerEnabled, for historical reasons,
there are a number of complex and intertwined interfaces that provide the same capability, which
legacy code relies on. This section specifies both the simple modern variant and the complicated
historical one.
Each user agent has a PDF viewer supported boolean, whose value is implementation-defined (and might vary according to user preferences).
The values of the above list form the PDF viewer mime types list.
Each NavigatorPlugins object has a plugins array, which is a new
PluginArray, and a mime types array, which is a new
MimeTypeArray.
The NavigatorPlugins mixin's javaEnabled() method steps are to return false.
Support in all current engines.
The NavigatorPlugins mixin's pdfViewerEnabled getter steps are to return
the user agent's PDF viewer supported.
The PluginArray interface supports named
properties. If the user agent's PDF viewer supported is true, then they are
the PDF viewer plugin names. Otherwise, they are the empty list.
The PluginArray interface supports indexed properties. The
supported property indices are the indices of this's
relevant global object's PDF viewer plugin objects.
The PluginArray interface's refresh() method steps are to do nothing.
The MimeTypeArray interface supports named
properties. If the user agent's PDF viewer supported is true, then they are
the PDF viewer mime types. Otherwise, they are the empty list.
The MimeTypeArray interface supports indexed properties. The
supported property indices are the indices of this's
relevant global object's PDF viewer mime type objects.
The MimeTypeArray interface's length getter steps are to return
this's relevant global object's PDF viewer mime type
objects's size.
The Plugin interface supports named properties. If the user agent's PDF viewer
supported is true, then they are the PDF viewer mime types. Otherwise, they
are the empty list.
The Plugin interface supports indexed properties.
The supported property indices are the indices of this's
relevant global object's PDF viewer mime type objects.
The Plugin interface's length getter steps are to return
this's relevant global object's PDF viewer mime type
objects's size.
The MimeType interface's enabledPlugin getter steps are to return
this's relevant global object's PDF viewer plugin
objects[0] (i.e., the generic "PDF Viewer" one).
Support in all current engines.
An ImageBitmap object represents a bitmap image that can be painted to a canvas
without undue latency.
An ImageBitmap object's bitmap has an origin-clean flag, which indicates whether the
bitmap is tainted by content from a different origin. The flag is initially set to
true and may be changed to false by the steps of createImageBitmap().
ImageBitmap objects are serializable objects and transferable
objects.
Their serialization steps, given value and serialized, are:
If value's origin-clean
flag is not set, then throw a "DataCloneError"
DOMException.
Set serialized.[[BitmapData]] to a copy of value's bitmap data.
Their deserialization steps, given serialized, value, and targetRealm, are:
Set value's bitmap data to serialized.[[BitmapData]].
Their transfer steps, given value and dataHolder, are:
If value's origin-clean
flag is not set, then throw a "DataCloneError"
DOMException.
Set dataHolder.[[BitmapData]] to value's bitmap data.
Unset value's bitmap data.
Their transfer-receiving steps, given dataHolder and value, are:
Set value's bitmap data to dataHolder.[[BitmapData]].
The ResizeQuality enumeration is used to express a preference for the
interpolation quality to use when scaling images.
To implement "pixelated", for each axis
independently, first determine the integer multiple of its natural size that puts it closest to
the target size and is greater than zero. Scale it to this integer-multiple-size using nearest
neighbor, then scale it the rest of the way to the target size using bilinear interpolation.
The "high" value indicates a preference for a high level
of image interpolation quality. High-quality image interpolation may be more computationally
expensive than lower settings.
Some objects include the AnimationFrameProvider interface mixin.
Each target object has a map of animation frame callbacks, which is an ordered map that must be initially empty, and an animation frame callback identifier, which is a number that must initially be zero.
Support in all current engines.
Support in all current engines.
MessageEvent interfaceSupport in all current engines.
Messages in server-sent events, cross-document messaging,
channel messaging, broadcast channels, and WebSockets use
the MessageEvent interface for their message
events: [WEBSOCKETS]
The initMessageEvent(type, bubbles,
cancelable, data, origin, lastEventId,
source, ports) method must initialize the event in a manner
analogous to the similarly-named initEvent() method.
[DOM]
Support in all current engines.
This section is non-normative.
To enable servers to push data to web pages over HTTP or using dedicated server-push protocols,
this specification introduces the EventSource interface.
Using this API consists of creating an EventSource object and registering an event
listener.
var source = new EventSource( 'updates.cgi' );
source. onmessage = function ( event) {
alert( event. data);
};
On the server-side, the script ("updates.cgi" in this case) sends
messages in the following form, with the text/event-stream MIME type:
data: This is the first message. data: This is the second message, it data: has two lines. data: This is the third message.
Authors can separate events by using different event types. Here is a stream that has two event types, "add" and "remove":
event: add data: 73857293 event: remove data: 2153 event: add data: 113411
The script to handle such a stream would look like this (where addHandler
and removeHandler are functions that take one argument, the event):
var source = new EventSource( 'updates.cgi' );
source. addEventListener( 'add' , addHandler, false );
source. addEventListener( 'remove' , removeHandler, false );
The default event type is "message".
Event streams are always decoded as UTF-8. There is no way to specify another character encoding.
Event stream requests can be redirected using HTTP 301 and 307 redirects as with normal HTTP requests. Clients will reconnect if the connection is closed; a client can be told to stop reconnecting using the HTTP 204 No Content response code.
Using this API rather than emulating it using XMLHttpRequest or an
iframe allows the user agent to make better use of network resources in cases where
the user agent implementer and the network operator are able to coordinate in advance. Amongst
other benefits, this can result in significant savings in battery life on portable devices. This
is discussed further in the section below on connectionless
push.
EventSource interfaceSupport in all current engines.
Each EventSource object has the following associated with it:
Apart from url these are not currently exposed on
the EventSource object.
When the object is created its readyState must
be set to CONNECTING (0). The rules given below
for handling the connection define when the value changes.
The following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the
EventSource interface:
| Event handler | Event handler event type |
|---|---|
onopen Support in all current engines. Firefox6+Safari5+Chrome6+ Opera12+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | open
|
onmessage Support in all current engines. Firefox6+Safari5+Chrome6+ Opera12+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | message
|
onerror Support in all current engines. Firefox6+Safari5+Chrome6+ Opera12+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | error
|
When a user agent is to fail the connection, the user agent must queue a
task which, if the readyState attribute is
set to a value other than CLOSED, sets the readyState attribute to CLOSED and fires an
event named error at the EventSource object.
Once the user agent has failed the connection,
it does not attempt to reconnect.
The task source for any tasks that are queued by EventSource objects is the remote event
task source.
Last-Event-ID` headerThe Last-Event-ID` HTTP request header reports an
EventSource object's last event ID
string to the server when the user agent is to reestablish the connection.
This event stream format's MIME type is text/event-stream.
The event stream format is as described by the stream production of the
following ABNF, the character set for which is Unicode. [ABNF]
stream = [ bom ] * event
event = * ( comment / field ) end-of-line
comment = colon * any-char end-of-line
field = 1* name-char [ colon [ space ] * any-char ] end-of-line
end-of-line = ( cr lf / cr / lf )
; characters
lf = %x000A ; U+000A LINE FEED (LF)
cr = %x000D ; U+000D CARRIAGE RETURN (CR)
space = %x0020 ; U+0020 SPACE
colon = %x003A ; U+003A COLON (:)
bom = %xFEFF ; U+FEFF BYTE ORDER MARK
name-char = %x0000-0009 / %x000B-000C / %x000E-0039 / %x003B-10FFFF
; a scalar value other than U+000A LINE FEED (LF), U+000D CARRIAGE RETURN (CR), or U+003A COLON (:)
any-char = %x0000-0009 / %x000B-000C / %x000E-10FFFF
; a scalar value other than U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR)
Event streams in this format must always be encoded as UTF-8. [ENCODING]
Lines must be separated by either a U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) character pair, a single U+000A LINE FEED (LF) character, or a single U+000D CARRIAGE RETURN (CR) character.
Since connections established to remote servers for such resources are expected to be long-lived, UAs should ensure that appropriate buffering is used. In particular, while line buffering with lines are defined to end with a single U+000A LINE FEED (LF) character is safe, block buffering or line buffering with different expected line endings can cause delays in event dispatch.
Streams must be decoded using the UTF-8 decode algorithm.
The stream must then be parsed by reading everything line by line, with a U+000D CARRIAGE RETURN U+000A LINE FEED (CRLF) character pair, a single U+000A LINE FEED (LF) character not preceded by a U+000D CARRIAGE RETURN (CR) character, and a single U+000D CARRIAGE RETURN (CR) character not followed by a U+000A LINE FEED (LF) character being the ways in which a line can end.
When a stream is parsed, a data buffer, an event type buffer, and a last event ID buffer must be associated with it. They must be initialized to the empty string.
Lines must be processed, in the order they are received, as follows:
Dispatch the event, as defined below.
Ignore the line.
Collect the characters on the line before the first U+003A COLON character (:), and let field be that string.
Collect the characters on the line after the first U+003A COLON character (:), and let value be that string. If value starts with a U+0020 SPACE character, remove it from value.
Process the field using the steps described below, using field as the field name and value as the field value.
Process the field using the steps described below, using the whole line as the field name, and the empty string as the field value.
Once the end of the file is reached, any pending data must be discarded. (If the file ends in the middle of an event, before the final empty line, the incomplete event is not dispatched.)
For web browsers, the appropriate steps to dispatch the event are as follows:
Set the last event ID string of the event source to the value of the last event ID buffer. The buffer does not get reset, so the last event ID string of the event source remains set to this value until the next time it is set by the server.
If the data buffer is an empty string, set the data buffer and the event type buffer to the empty string and return.
If the data buffer's last character is a U+000A LINE FEED (LF) character, then remove the last character from the data buffer.
Let event be the result of creating an event using
MessageEvent, in the relevant realm of
the EventSource object.
Initialize event's type attribute to
"message", its data attribute to data, its origin attribute to the serialization of the origin of the
event stream's final URL (i.e., the URL after redirects), and its lastEventId attribute to the last event ID string of the event
source.
If the event type buffer has a value other than the empty string, change the type of the newly created event to equal the value of the event type buffer.
Set the data buffer and the event type buffer to the empty string.
Queue a task which, if the readyState attribute is set to a value other than CLOSED, dispatches the newly created event at the
EventSource object.
For other user agents, the appropriate steps to dispatch the event are implementation dependent, but at a minimum they must set the data and event type buffers to the empty string before returning.
Legacy proxy servers are known to, in certain cases, drop HTTP connections after a short timeout. To protect against such proxy servers, authors can include a comment line (one starting with a ':' character) every 15 seconds or so.
Authors wishing to relate event source connections to each other or to specific documents previously served might find that relying on IP addresses doesn't work, as individual clients can have multiple IP addresses (due to having multiple proxy servers) and individual IP addresses can have multiple clients (due to sharing a proxy server). It is better to include a unique identifier in the document when it is served and then pass that identifier as part of the URL when the connection is established.
Authors are also cautioned that HTTP chunking can have unexpected negative effects on the reliability of this protocol, in particular if the chunking is done by a different layer unaware of the timing requirements. If this is a problem, chunking can be disabled for serving event streams.
Clients that support HTTP's per-server connection limitation might run into trouble when
opening multiple pages from a site if each page has an EventSource to the same
domain. Authors can avoid this using the relatively complex mechanism of using unique domain names
per connection, or by allowing the user to enable or disable the EventSource
functionality on a per-page basis, or by sharing a single EventSource object using a
shared worker.
User agents running in controlled environments, e.g. browsers on mobile handsets tied to specific carriers, may offload the management of the connection to a proxy on the network. In such a situation, the user agent for the purposes of conformance is considered to include both the handset software and the network proxy.
This can reduce the total data usage, and can therefore result in considerable power savings.
As well as implementing the existing API and text/event-stream wire format as
defined by this specification and in more distributed ways as described above, formats of event
framing defined by other applicable specifications may be supported. This
specification does not define how they are to be parsed or processed.
While an EventSource object's readyState is CONNECTING, and the object has one or more event
listeners registered for open, message, or error events, there must
be a strong reference from the Window or WorkerGlobalScope object that
the EventSource object's constructor was invoked from to the EventSource
object itself.
While an EventSource object's readyState is OPEN, and the object has one or more event listeners
registered for message or error events, there must be a strong reference from the
Window or WorkerGlobalScope object that the EventSource
object's constructor was invoked from to the EventSource object itself.
While there is a task queued by an EventSource object on the remote event
task source, there must be a strong reference from the Window or
WorkerGlobalScope object that the EventSource object's constructor was
invoked from to that EventSource object.
If an EventSource object is garbage collected while its connection is still open,
the user agent must abort any instance of the fetch algorithm
opened by this EventSource.
This section is non-normative.
User agents are strongly urged to provide detailed diagnostic information about
EventSource objects and their related network connections in their development
consoles, to aid authors in debugging code using this API.
For example, a user agent could have a panel displaying all the EventSource
objects a page has created, each listing the constructor's arguments, whether there was a network
error, what the CORS status of the connection is and what headers were sent by the client and
received from the server to lead to that status, the messages that were received and how they were
parsed, and so forth.
Implementations are especially encouraged to report detailed information to their development
consoles whenever an error event is fired, since little to no
information can be made available in the events themselves.
Support in all current engines.
Web browsers, for security and privacy reasons, prevent documents in different domains from affecting each other; that is, cross-site scripting is disallowed.
While this is an important security feature, it prevents pages from different domains from communicating even when those pages are not hostile. This section introduces a messaging system that allows documents to communicate with each other regardless of their source domain, in a way designed to not enable cross-site scripting attacks.
This section is non-normative.
Authors should check the origin attribute to
ensure that messages are only accepted from domains that they expect to receive messages from.
Otherwise, bugs in the author's message handling code could be exploited by hostile sites.
Furthermore, even after checking the origin
attribute, authors should also check that the data in question is of the expected format.
Otherwise, if the source of the event has been attacked using a cross-site scripting flaw, further
unchecked processing of information sent using the postMessage() method could result in the attack being
propagated into the receiver.
Authors should not use the wildcard keyword (*) in the targetOrigin argument in messages that contain any confidential information, as otherwise there is no way to guarantee that the message is only delivered to the recipient to which it was intended.
Authors who accept messages from any origin are encouraged to consider the risks of a denial-of-service attack. An attacker could send a high volume of messages; if the receiving page performs expensive computation or causes network traffic to be sent for each such message, the attacker's message could be multiplied into a denial-of-service attack. Authors are encouraged to employ rate limiting (only accepting a certain number of messages per minute) to make such attacks impractical.
The integrity of this API is based on the inability for scripts of one origin to
post arbitrary events (using dispatchEvent() or otherwise) to objects in
other origins (those that are not the same).
User agents are also encouraged to consider rate-limiting message traffic between different origins, to protect naïve sites from denial-of-service attacks.
The Window interface's postMessage(message, targetOrigin,
transfer) method steps are to run the window post message
steps given this, message, and «[ "targetOrigin" →
targetOrigin, "transfer"
→ transfer ]».
Support in all current engines.
Channel_Messaging_API/Using_channel_messaging
Support in all current engines.
This section is non-normative.
To enable independent pieces of code (e.g. running in different browsing contexts) to communicate directly, authors can use channel messaging.
Communication channels in this mechanism are implemented as two-ways pipes, with a port at each end. Messages sent in one port are delivered at the other port, and vice-versa. Messages are delivered as DOM events, without interrupting or blocking running tasks.
To create a connection (two "entangled" ports), the MessageChannel()
constructor is called:
var channel = new MessageChannel();
One of the ports is kept as the local port, and the other port is sent to the remote code, e.g.
using postMessage():
otherWindow. postMessage( 'hello' , 'https://example.com' , [ channel. port2]);
To send messages, the postMessage() method on
the port is used:
channel. port1. postMessage( 'hello' );
To receive messages, one listens to message events:
channel. port1. onmessage = handleMessage;
function handleMessage( event) {
// message is in event.data
// ...
}
Data sent on a port can be structured data; for example here an array of strings is passed on a
MessagePort:
port1. postMessage([ 'hello' , 'world' ]);
This section is non-normative.
This section is non-normative.
Ports can be viewed as a way to expose limited capabilities (in the object-capability model sense) to other actors in the system. This can either be a weak capability system, where the ports are merely used as a convenient model within a particular origin, or as a strong capability model, where they are provided by one origin provider as the only mechanism by which another origin consumer can effect change in or obtain information from provider.
For example, consider a situation in which a social web site embeds in one iframe
the user's email contacts provider (an address book site, from a second origin), and in a second
iframe a game (from a third origin). The outer social site and the game in the second
iframe cannot access anything inside the first iframe; together they can
only:
Navigate the iframe to a new URL, such as the same
URL but with a different fragment,
causing the Window in the iframe to receive a hashchange event.
Resize the iframe, causing the Window in the iframe
to receive a resize event.
Send a message event to the Window in the
iframe using the window.postMessage()
API.
The contacts provider can use these methods, most particularly the third one, to provide an API
that can be accessed by other origins to manipulate the user's address book. For example, it could
respond to a message "add-contact Guillaume Tell
<tell@pomme.example.net>" by adding the given person and email address to the user's
address book.
To avoid any site on the web being able to manipulate the user's contacts, the contacts provider might only allow certain trusted sites, such as the social site, to do this.
Now suppose the game wanted to add a contact to the user's address book, and that the social site was willing to allow it to do so on its behalf, essentially "sharing" the trust that the contacts provider had with the social site. There are several ways it could do this; most simply, it could just proxy messages between the game site and the contacts site. However, this solution has a number of difficulties: it requires the social site to either completely trust the game site not to abuse the privilege, or it requires that the social site verify each request to make sure it's not a request that it doesn't want to allow (such as adding multiple contacts, reading the contacts, or deleting them); it also requires some additional complexity if there's ever the possibility of multiple games simultaneously trying to interact with the contacts provider.
Using message channels and MessagePort objects, however, all of these problems can
go away. When the game tells the social site that it wants to add a contact, the social site can
ask the contacts provider not for it to add a contact, but for the capability to add a
single contact. The contacts provider then creates a pair of MessagePort objects, and
sends one of them back to the social site, who forwards it on to the game. The game and the
contacts provider then have a direct connection, and the contacts provider knows to only honor a
single "add contact" request, nothing else. In other words, the game has been granted the
capability to add a single contact.
This section is non-normative.
Continuing the example from the previous section, consider the contacts provider in particular.
While an initial implementation might have simply used XMLHttpRequest objects in the
service's iframe, an evolution of the service might instead want to use a shared worker with a single WebSocket connection.
If the initial design used MessagePort objects to grant capabilities, or even just
to allow multiple simultaneous independent sessions, the service implementation can switch from
the XMLHttpRequests-in-each-iframe model to the
shared-WebSocket model without changing the API at all: the ports on the service
provider side can all be forwarded to the shared worker without it affecting the users of the API
in the slightest.
Support in all current engines.
A MessageChannel object has an associated port 1 and an associated
port 2, both MessagePort objects.
The port2 getter steps are to return
this's port 2.
MessageEventTarget mixinThe following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by objects implementing the
MessageEventTarget interface:
| Event handler | Event handler event type |
|---|---|
onmessage Support in all current engines. Firefox41+Safari5+Chrome2+ Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ DedicatedWorkerGlobalScope/message_event Support in all current engines. Firefox3.5+Safari4+Chrome4+ Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ | message
|
onmessageerror MessagePort/messageerror_event Support in all current engines. Firefox57+Safari16.4+Chrome60+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ DedicatedWorkerGlobalScope/messageerror_event Support in all current engines. Firefox57+Safari16.4+Chrome60+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ | messageerror
|
Support in all current engines.
Each channel has two message ports. Data sent through one port is received by the other port, and vice versa.
Each MessagePort object can be entangled with another (a symmetric relationship).
Each MessagePort object also has a task source called the port
message queue, initially empty. A port message queue can be enabled or
disabled, and is initially disabled. Once enabled, a port can never be disabled again (though
messages in the queue can get moved to another queue or removed altogether, which has much the
same effect). A MessagePort also has a has been shipped flag, which must
initially be false.
When a port's port message queue is enabled, the event loop must use
it as one of its task sources. When a port's relevant
global object is a Window, all tasks queued on its port message queue must be associated with
the port's relevant global object's associated
Document.
When a MessagePort's has been shipped flag is false, its port
message queue must be ignored for the purposes of the event loop. (The
unshipped port message queue is used instead.)
MessagePort objects are transferable
objects. Their transfer steps, given value and
dataHolder, are:
Set value's has been shipped flag to true.
Set dataHolder.[[PortMessageQueue]] to value's port message queue.
If value is entangled with another port remotePort, then:
Set remotePort's has been shipped flag to true.
Set dataHolder.[[RemotePort]] to remotePort.
Otherwise, set dataHolder.[[RemotePort]] to null.
Their transfer-receiving steps, given dataHolder and value, are:
Set value's has been shipped flag to true.
Move all the tasks that are to fire message events in dataHolder.[[PortMessageQueue]] to the
port message queue of value, if any, leaving value's
port message queue in its initial disabled state, and, if value's
relevant global object is a Window, associating the moved tasks with value's relevant global object's
associated Document.
If dataHolder.[[RemotePort]] is not null, then entangle dataHolder.[[RemotePort]] and value. (This will disentangle dataHolder.[[RemotePort]] from the original port that was transferred.)
The start()
method steps are to enable this's port message queue, if it is not
already enabled.
The following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the
MessagePort interface:
| Event handler | Event handler event type |
|---|---|
onclose | close
|
The first time a MessagePort object's onmessage IDL attribute is set, the port's
port message queue must be enabled, as if the start() method had been called.
When a MessagePort object o is garbage collected, if o is
entangled, then the user agent must disentangle
o.
When a MessagePort object o is entangled and message or messageerror
event listener is registered, user agents must act as if o's entangled
MessagePort object has a strong reference to o.
Furthermore, a MessagePort object must not be garbage collected while there
exists an event referenced by a task in a task
queue that is to be dispatched on that MessagePort object, or while the
MessagePort object's port message queue is enabled and not empty.
Support in all current engines.
Support in all current engines.
Pages on a single origin opened by the same user in the same user agent but in different unrelated browsing contexts sometimes need to send notifications to each other, for example "hey, the user logged in over here, check your credentials again".
For elaborate cases, e.g. to manage locking of shared state, to manage synchronization of
resources between a server and multiple local clients, to share a WebSocket
connection with a remote host, and so forth, shared workers are
the most appropriate solution.
For simple cases, though, where a shared worker would be an unreasonable overhead, authors can use the simple channel-based broadcast mechanism described in this section.
While a BroadcastChannel object whose closed flag is false has an event listener
registered for message or messageerror events, there must be a strong reference from the
BroadcastChannel object's relevant global object to the
BroadcastChannel object itself.
The close() method steps are to set
this's closed flag to true.
The following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the
BroadcastChannel interface:
| Event handler | Event handler event type |
|---|---|
onmessage BroadcastChannel/message_event Support in all current engines. Firefox38+Safari15.4+Chrome54+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | message
|
onmessageerror BroadcastChannel/messageerror_event Support in all current engines. Firefox57+Safari15.4+Chrome60+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ | messageerror
|
Support in all current engines.
This section is non-normative.
This specification defines an API for running scripts in the background independently of any user interface scripts.
This allows for long-running scripts that are not interrupted by scripts that respond to clicks or other user interactions, and allows long tasks to be executed without yielding to keep the page responsive.
Workers (as these background scripts are called herein) are relatively heavy-weight, and are not intended to be used in large numbers. For example, it would be inappropriate to launch one worker for each pixel of a four megapixel image. The examples below show some appropriate uses of workers.
Generally, workers are expected to be long-lived, have a high start-up performance cost, and a high per-instance memory cost.
This section is non-normative.
There are a variety of uses that workers can be put to. The following subsections show various examples of this use.
This section is non-normative.
The simplest use of workers is for performing a computationally expensive task without interrupting the user interface.
In this example, the main document spawns a worker to (naïvely) compute prime numbers, and progressively displays the most recently found prime number.
The main page is as follows:
The Worker() constructor call creates a worker and returns a
Worker object representing that worker, which is used to communicate with the worker.
That object's onmessage event handler
allows the code to receive messages from the worker.
The worker itself is as follows:
var n = 1 ;
search: while ( true ) {
n += 1 ;
for ( var i = 2 ; i <= Math. sqrt( n); i += 1 )
if ( n % i == 0 )
continue search;
// found a prime!
postMessage( n);
}
The bulk of this code is simply an unoptimized search for a prime number. The postMessage() method is used to send a
message back to the page when a prime is found.
This section is non-normative.
All of our examples so far show workers that run classic
scripts. Workers can instead be instantiated using module
scripts, which have the usual benefits: the ability to use the JavaScript
import statement to import other modules; strict mode by default; and
top-level declarations not polluting the worker's global scope.
As the import statement is available, the importScripts() method will automatically fail
inside module workers.
In this example, the main document uses a worker to do off-main-thread image manipulation. It imports the filters used from another module.
The main page is as follows:
The worker file is then:
import * as filters from "./filters.js" ;
self. onmessage = e => {
const { imageData, filter } = e. data;
filters[ filter]( imageData);
self. postMessage( imageData, [ imageData. data. buffer]);
};
Which imports the file filters.js:
export function none() {}
export function grayscale({ data: d }) {
for ( let i = 0 ; i < d. length; i += 4 ) {
const [ r, g, b] = [ d[ i], d[ i + 1 ], d[ i + 2 ]];
// CIE luminance for the RGB
// The human eye is bad at seeing red and blue, so we de-emphasize them.
d[ i] = d[ i + 1 ] = d[ i + 2 ] = 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
};
export function brighten({ data: d }) {
for ( let i = 0 ; i < d. length; ++ i) {
d[ i] *= 1.2 ;
}
};
Support in all current engines.
This section is non-normative.
This section introduces shared workers using a Hello World example. Shared workers use slightly different APIs, since each worker can have multiple connections.
This first example shows how you connect to a worker and how a worker can send a message back to the page when it connects to it. Received messages are displayed in a log.
Here is the HTML page:
Here is the JavaScript worker:
onconnect = function ( e) {
var port = e. ports[ 0 ];
port. postMessage( 'Hello World!' );
}
This second example extends the first one by changing two things: first, messages are received
using addEventListener() instead of an event handler IDL attribute, and second, a message is sent to the
worker, causing the worker to send another message in return. Received messages are again
displayed in a log.
Here is the HTML page:
Here is the JavaScript worker:
onconnect = function ( e) {
var port = e. ports[ 0 ];
port. postMessage( 'Hello World!' );
port. onmessage = function ( e) {
port. postMessage( 'pong' ); // not e.ports[0].postMessage!
// e.target.postMessage('pong'); would work also
}
}
Finally, the example is extended to show how two pages can connect to the same worker; in this
case, the second page is merely in an iframe on the first page, but the same
principle would apply to an entirely separate page in a separate top-level
traversable.
Here is the outer HTML page:
Here is the inner HTML page:
Here is the JavaScript worker:
var count = 0 ;
onconnect = function ( e) {
count += 1 ;
var port = e. ports[ 0 ];
port. postMessage( 'Hello World! You are connection #' + count);
port. onmessage = function ( e) {
port. postMessage( 'pong' );
}
}
This section is non-normative.
In this example, multiple windows (viewers) can be opened that are all viewing the same map. All the windows share the same map information, with a single worker coordinating all the viewers. Each viewer can move around independently, but if they set any data on the map, all the viewers are updated.
The main page isn't interesting, it merely provides a way to open the viewers:
The viewer is more involved:
There are several key things worth noting about the way the viewer is written.
Multiple listeners. Instead of a single message processing function, the code here attaches multiple event listeners, each one performing a quick check to see if it is relevant for the message. In this example it doesn't make much difference, but if multiple authors wanted to collaborate using a single port to communicate with a worker, it would allow for independent code instead of changes having to all be made to a single event handling function.
Registering event listeners in this way also allows you to unregister specific listeners when
you are done with them, as is done with the configure() method in this
example.
Finally, the worker:
var nextName = 0 ;
function getNextName() {
// this could use more friendly names
// but for now just return a number
return nextName++ ;
}
var map = [
[ 0 , 0 , 0 , 0 , 0 , 0 , 0 ],
[ 1 , 1 , 0 , 1 , 0 , 1 , 1 ],
[ 0 , 1 , 0 , 1 , 0 , 0 , 0 ],
[ 0 , 1 , 0 , 1 , 0 , 1 , 1 ],
[ 0 , 0 , 0 , 1 , 0 , 0 , 0 ],
[ 1 , 0 , 0 , 1 , 1 , 1 , 1 ],
[ 1 , 1 , 0 , 1 , 1 , 0 , 1 ],
];
function wrapX( x) {
if ( x < 0 ) return wrapX( x + map[ 0 ]. length);
if ( x >= map[ 0 ]. length) return wrapX( x - map[ 0 ]. length);
return x;
}
function wrapY( y) {
if ( y < 0 ) return wrapY( y + map. length);
if ( y >= map[ 0 ]. length) return wrapY( y - map. length);
return y;
}
function wrap( val, min, max) {
if ( val < min)
return val + ( max- min) + 1 ;
if ( val > max)
return val - ( max- min) - 1 ;
return val;
}
function sendMapData( viewer) {
var data = '' ;
for ( var y = viewer. y- 1 ; y <= viewer. y+ 1 ; y += 1 ) {
for ( var x = viewer. x- 1 ; x <= viewer. x+ 1 ; x += 1 ) {
if ( data != '' )
data += ',' ;
data += map[ wrap( y, 0 , map[ 0 ]. length- 1 )][ wrap( x, 0 , map. length- 1 )];
}
}
viewer. port. postMessage( 'map ' + data);
}
var viewers = {};
onconnect = function ( event) {
var name = getNextName();
event. ports[ 0 ]. _data = { port: event. ports[ 0 ], name: name, x: 0 , y: 0 , };
viewers[ name] = event. ports[ 0 ]. _data;
event. ports[ 0 ]. postMessage( 'cfg ' + name);
event. ports[ 0 ]. onmessage = getMessage;
sendMapData( event. ports[ 0 ]. _data);
};
function getMessage( event) {
switch ( event. data. substr( 0 , 4 )) {
case 'mov ' :
var direction = event. data. substr( 4 );
var dx = 0 ;
var dy = 0 ;
switch ( direction) {
case 'up' : dy = - 1 ; break ;
case 'down' : dy = 1 ; break ;
case 'left' : dx = - 1 ; break ;
case 'right' : dx = 1 ; break ;
}
event. target. _data. x = wrapX( event. target. _data. x + dx);
event. target. _data. y = wrapY( event. target. _data. y + dy);
sendMapData( event. target. _data);
break ;
case 'set ' :
var value = event. data. substr( 4 );
map[ event. target. _data. y][ event. target. _data. x] = value;
for ( var viewer in viewers)
sendMapData( viewers[ viewer]);
break ;
case 'txt ' :
var name = event. target. _data. name;
var message = event. data. substr( 4 );
for ( var viewer in viewers)
viewers[ viewer]. port. postMessage( 'txt ' + name + ' ' + message);
break ;
case 'msg ' :
var party1 = event. target. _data;
var party2 = viewers[ event. data. substr( 4 ). split( ' ' , 1 )[ 0 ]];
if ( party2) {
var channel = new MessageChannel();
party1. port. postMessage( 'msg ' + party2. name, [ channel. port1]);
party2. port. postMessage( 'msg ' + party1. name, [ channel. port2]);
}
break ;
}
}
Connecting to multiple pages. The script uses the onconnect event listener to listen for
multiple connections.
Direct channels. When the worker receives a "msg" message from one viewer naming another viewer, it sets up a direct connection between the two, so that the two viewers can communicate directly without the worker having to proxy all the messages.
This section is non-normative.
With multicore CPUs becoming prevalent, one way to obtain better performance is to split computationally expensive tasks amongst multiple workers. In this example, a computationally expensive task that is to be performed for every number from 1 to 10,000,000 is farmed out to ten subworkers.
The main page is as follows, it just reports the result:
The worker itself is as follows:
// settings
var num_workers = 10 ;
var items_per_worker = 1000000 ;
// start the workers
var result = 0 ;
var pending_workers = num_workers;
for ( var i = 0 ; i < num_workers; i += 1 ) {
var worker = new Worker( 'core.js' );
worker. postMessage( i * items_per_worker);
worker. postMessage(( i+ 1 ) * items_per_worker);
worker. onmessage = storeResult;
}
// handle the results
function storeResult( event) {
result += 1 * event. data;
pending_workers -= 1 ;
if ( pending_workers <= 0 )
postMessage( result); // finished!
}
It consists of a loop to start the subworkers, and then a handler that waits for all the subworkers to respond.
The subworkers are implemented as follows:
var start;
onmessage = getStart;
function getStart( event) {
start = 1 * event. data;
onmessage = getEnd;
}
var end;
function getEnd( event) {
end = 1 * event. data;
onmessage = null ;
work();
}
function work() {
var result = 0 ;
for ( var i = start; i < end; i += 1 ) {
// perform some complex calculation here
result += 1 ;
}
postMessage( result);
close();
}
They receive two numbers in two events, perform the computation for the range of numbers thus specified, and then report the result back to the parent.
This section is non-normative.
Suppose that a cryptography library is made available that provides three tasks:
The library itself is as follows:
function handleMessage( e) {
if ( e. data == "genkeys" )
genkeys( e. ports[ 0 ]);
else if ( e. data == "encrypt" )
encrypt( e. ports[ 0 ]);
else if ( e. data == "decrypt" )
decrypt( e. ports[ 0 ]);
}
function genkeys( p) {
var keys = _generateKeyPair();
p. postMessage( keys[ 0 ]);
p. postMessage( keys[ 1 ]);
}
function encrypt( p) {
var key, state = 0 ;
p. onmessage = function ( e) {
if ( state == 0 ) {
key = e. data;
state = 1 ;
} else {
p. postMessage( _encrypt( key, e. data));
}
};
}
function decrypt( p) {
var key, state = 0 ;
p. onmessage = function ( e) {
if ( state == 0 ) {
key = e. data;
state = 1 ;
} else {
p. postMessage( _decrypt( key, e. data));
}
};
}
// support being used as a shared worker as well as a dedicated worker
if ( 'onmessage' in this ) // dedicated worker
onmessage = handleMessage;
else // shared worker
onconnect = function ( e) { e. port. onmessage = handleMessage; }
// the "crypto" functions:
function _generateKeyPair() {
return [ Math. random(), Math. random()];
}
function _encrypt( k, s) {
return 'encrypted-' + k + ' ' + s;
}
function _decrypt( k, s) {
return s. substr( s. indexOf( ' ' ) + 1 );
}
Note that the crypto functions here are just stubs and don't do real cryptography.
This library could be used as follows:
A later version of the API, though, might want to offload all the crypto work onto subworkers. This could be done as follows:
function handleMessage( e) {
if ( e. data == "genkeys" )
genkeys( e. ports[ 0 ]);
else if ( e. data == "encrypt" )
encrypt( e. ports[ 0 ]);
else if ( e. data == "decrypt" )
decrypt( e. ports[ 0 ]);
}
function genkeys( p) {
var generator = new Worker( 'libcrypto-v2-generator.js' );
generator. postMessage( '' , [ p]);
}
function encrypt( p) {
p. onmessage = function ( e) {
var key = e. data;
var encryptor = new Worker( 'libcrypto-v2-encryptor.js' );
encryptor. postMessage( key, [ p]);
};
}
function encrypt( p) {
p. onmessage = function ( e) {
var key = e. data;
var decryptor = new Worker( 'libcrypto-v2-decryptor.js' );
decryptor. postMessage( key, [ p]);
};
}
// support being used as a shared worker as well as a dedicated worker
if ( 'onmessage' in this ) // dedicated worker
onmessage = handleMessage;
else // shared worker
onconnect = function ( e) { e. ports[ 0 ]. onmessage = handleMessage };
The little subworkers would then be as follows.
For generating key pairs:
onmessage = function ( e) {
var k = _generateKeyPair();
e. ports[ 0 ]. postMessage( k[ 0 ]);
e. ports[ 0 ]. postMessage( k[ 1 ]);
close();
}
function _generateKeyPair() {
return [ Math. random(), Math. random()];
}
For encrypting:
onmessage = function ( e) {
var key = e. data;
e. ports[ 0 ]. onmessage = function ( e) {
var s = e. data;
postMessage( _encrypt( key, s));
}
}
function _encrypt( k, s) {
return 'encrypted-' + k + ' ' + s;
}
For decrypting:
onmessage = function ( e) {
var key = e. data;
e. ports[ 0 ]. onmessage = function ( e) {
var s = e. data;
postMessage( _decrypt( key, s));
}
}
function _decrypt( k, s) {
return s. substr( s. indexOf( ' ' ) + 1 );
}
Notice how the users of the API don't have to even know that this is happening — the API hasn't changed; the library can delegate to subworkers without changing its API, even though it is accepting data using message channels.
This section is non-normative.
Creating a worker requires a URL to a JavaScript file. The Worker() constructor is invoked with the URL to that file as its only
argument; a worker is then created and returned:
var worker = new Worker( 'helper.js' );
If you want your worker script to be interpreted as a module script instead of the default classic script, you need to use a slightly different signature:
var worker = new Worker( 'helper.mjs' , { type: "module" });
This section is non-normative.
Dedicated workers use MessagePort objects behind the scenes, and thus support all
the same features, such as sending structured data, transferring binary data, and transferring
other ports.
To receive messages from a dedicated worker, use the onmessage event handler IDL attribute on the Worker object:
worker. onmessage = function ( event) { ... };
You can also use the addEventListener()
method.
To send data to a worker, use the postMessage() method. Structured data can be sent over this
communication channel. To send ArrayBuffer objects
efficiently (by transferring them rather than cloning them), list them in an array in the second
argument.
worker. postMessage({
operation: 'find-edges' ,
input: buffer, // an ArrayBuffer object
threshold: 0.6 ,
}, [ buffer]);
To receive a message inside the worker, the onmessage event handler IDL attribute is used.
onmessage = function ( event) { ... };
You can again also use the addEventListener() method.
In either case, the data is provided in the event object's data attribute.
To send messages back, you again use postMessage(). It supports the
structured data in the same manner.
postMessage( event. data. input, [ event. data. input]); // transfer the buffer back
Support in all current engines.
This section is non-normative.
Shared workers are identified by the URL of the script used to create it, optionally with an explicit name. The name allows multiple instances of a particular shared worker to be started.
Shared workers are scoped by origin. Two different sites using the same names will not collide. However, if a page tries to use the same shared worker name as another page on the same site, but with a different script URL, it will fail.
Creating shared workers is done using the SharedWorker()
constructor. This constructor takes the URL to the script to use for its first argument, and the
name of the worker, if any, as the second argument.
var worker = new SharedWorker( 'service.js' );
Communicating with shared workers is done with explicit MessagePort objects. The
object returned by the SharedWorker() constructor holds a
reference to the port on its port attribute.
worker. port. onmessage = function ( event) { ... };
worker. port. postMessage( 'some message' );
worker. port. postMessage({ foo: 'structured' , bar: [ 'data' , 'also' , 'possible' ]});
Inside the shared worker, new clients of the worker are announced using the connect event. The port for the new client is
given by the event object's source attribute.
onconnect = function ( event) {
var newPort = event. source;
// set up a listener
newPort. onmessage = function ( event) { ... };
// send a message back to the port
newPort. postMessage( 'ready!' ); // can also send structured data, of course
};
This standard defines two kinds of workers: dedicated workers, and shared workers. Dedicated workers, once created, are linked to their creator, but message ports can be used to communicate from a dedicated worker to multiple other browsing contexts or workers. Shared workers, on the other hand, are named, and once created any script running in the same origin can obtain a reference to that worker and communicate with it. Service Workers defines a third kind. [SW]
The global scope is the "inside" of a worker.
WorkerGlobalScope common interfaceSupport in all current engines.
WorkerGlobalScope serves as the base class for specific types of worker global
scope objects, including DedicatedWorkerGlobalScope,
SharedWorkerGlobalScope, and ServiceWorkerGlobalScope.
The location attribute must return the
WorkerLocation object whose associated WorkerGlobalScope object is
the WorkerGlobalScope object.
The following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by objects implementing the
WorkerGlobalScope interface:
| Event handler | Event handler event type |
|---|---|
onerror Support in all current engines. Firefox3.5+Safari4+Chrome4+ Opera11.5+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android? | error
|
onlanguagechange WorkerGlobalScope/languagechange_event Support in all current engines. Firefox74+Safari4+Chrome4+ Opera11.5+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | languagechange
|
onoffline WorkerGlobalScope/offline_event Firefox29+Safari8+ChromeNo Opera?EdgeNo Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | offline
|
ononline WorkerGlobalScope/online_event Firefox29+Safari8+ChromeNo Opera?EdgeNo Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | online
|
onrejectionhandled | rejectionhandled
|
onunhandledrejection | unhandledrejection
|
DedicatedWorkerGlobalScope interfaceSupport in all current engines.
The close() method steps are to
close a worker given this.
SharedWorkerGlobalScope interfaceSupport in all current engines.
Shared workers receive message ports through connect events on their SharedWorkerGlobalScope object for each
connection.
The close() method steps are to close a
worker given this.
The following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by objects implementing the
SharedWorkerGlobalScope interface:
| Event handler | Event handler event type |
|---|---|
onconnect SharedWorkerGlobalScope/connect_event Support in all current engines. Firefox29+Safari16+Chrome4+ Opera10.6+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS16+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | connect
|
A worker event loop's task queues only have events, callbacks, and networking activity as tasks. These worker event loops are created by the run a worker algorithm.
Once the WorkerGlobalScope's closing flag is set to true, the event
loop's task queues must discard any
further tasks that would be added to them (tasks already on the
queue are unaffected except where otherwise specified). Effectively, once the closing flag is true, timers stop firing,
notifications for all pending background operations are dropped, etc.
Workers communicate with other workers and with Windows through message channels and their MessagePort
objects.
Given an environment settings
object o when creating or obtaining a worker, the relevant owner to
add depends on the type of global
object specified by o. If o's global object is a WorkerGlobalScope
object (i.e., if we are creating a nested dedicated worker), then the relevant owner is that
global object. Otherwise, o's global
object is a Window object, and the relevant owner is that
Window's associated
Document.
A worker is said to be a suspendable worker if it is not an active needed worker but it is a permissible worker.
User agents may invoke the terminate a worker algorithm when a worker stops being an active needed worker and the worker continues executing even after its closing flag was set to true.
Whenever an uncaught runtime script error occurs in one of the worker's scripts, if the error
did not occur while handling a previous script error, the user agent will report it for the worker's WorkerGlobalScope object.
AbstractWorker mixinThe following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by objects implementing the
AbstractWorker interface:
| Event handler | Event handler event type |
|---|---|
onerror Support in all current engines. Firefox44+Safari11.1+Chrome40+ Opera?Edge79+ Edge (Legacy)17+Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? Support in all current engines. Firefox29+Safari16+Chrome5+ Opera10.6+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android33+Safari iOS16+Chrome AndroidNoWebView Android?Samsung Internet4.0–5.0Opera Android11–14 Support in all current engines. Firefox3.5+Safari4+Chrome4+ Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android11+ | error
|
Worker interfaceSupport in all current engines.
The postMessage(message, transfer)
and postMessage(message,
options) methods on Worker objects act as if, when invoked,
they immediately invoked the respective postMessage(message, transfer)
and postMessage(message,
options) on this's outside port, with the same
arguments, and returned the same return value.
SharedWorker interfaceSupport in all current engines.
User agents should err toward exposing the number of logical processors available, using lower values only in cases where there are user-agent specific limits in place (such as a limitation on the number of workers that can be created) or when the user agent desires to limit fingerprinting possibilities.
WorkerNavigator interfaceSupport in all current engines.
The navigator attribute of the
WorkerGlobalScope interface must return an instance of the
WorkerNavigator interface, which represents the identity and state of the user agent
(the client):
WorkerLocation interfaceSupport in all current engines.
Support in all current engines.
A WorkerLocation object has an associated WorkerGlobalScope object (a
WorkerGlobalScope object).
Support in all current engines.
The href getter steps are to return this's
WorkerGlobalScope
object's url, serialized.
Support in all current engines.
The origin getter steps are to return the serialization of this's WorkerGlobalScope object's
url's origin.
Support in all current engines.
The protocol getter steps are to return
this's WorkerGlobalScope object's
url's scheme, followed by ":".
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
The pathname getter steps are to return the result
of URL path serializing this's WorkerGlobalScope object's
url.
Support in all current engines.
Support in all current engines.
This section is non-normative.
Worklets are a piece of specification infrastructure which can be used for running scripts independent of the main JavaScript execution environment, while not requiring any particular implementation model.
The worklet infrastructure specified here cannot be used directly by web developers. Instead, other specifications build upon it to create directly-usable worklet types, specialized for running in particular parts of the browser implementation pipeline.
This section is non-normative.
Allowing extension points to rendering, or other sensitive parts of the implementation pipeline
such as audio output, is difficult. If extension points were done with full access to the APIs
available on Window, engines would need to abandon previously-held assumptions for
what could happen in the middle of those phases. For example, during the layout phase, rendering
engines assume that no DOM will be modified.
Additionally, defining extension points in the Window environment would restrict
user agents to performing work in the same thread as the Window object. (Unless
implementations added complex, high-overhead infrastructure to allow thread-safe APIs, as well
as thread-joining guarantees.)
Worklets are designed to allow extension points, while keeping guarantees that user agents
currently rely on. This is done through new global environments, based on subclasses of
WorkletGlobalScope.
Worklets are similar to web workers. However, they:
Are thread-agnostic. That is, they are not designed to run on a dedicated separate thread, like each worker is. Implementations can run worklets wherever they choose (including on the main thread).
Are able to have multiple duplicate instances of the global scope created, for the purpose of parallelism.
Do not use an event-based API. Instead, classes are registered on the global scope, whose methods are invoked by the user agent.
Have a reduced API surface on the global scope.
Have a lifetime for their global object which is defined by other specifications, often in an implementation-defined manner.
As worklets have relatively high overhead, they are best used sparingly. Due to this, a given
WorkletGlobalScope is expected to be shared between multiple separate scripts. (This
is similar to how a single Window is shared between multiple separate scripts.)
Worklets are a general technology that serve different use cases. Some worklets, such as those defined in CSS Painting API, provide extension points intended for stateless, idempotent, and short-running computations, which have special considerations as described in the next couple of sections. Others, such as those defined in Web Audio API, are used for stateful, long-running operations. [CSSPAINT] [WEBAUDIO]
Some specifications which use worklets are intended to allow user agents to parallelize work over multiple threads, or to move work between threads as required. In these specifications, user agents might invoke methods on a web-developer-provided class in an implementation-defined order.
As a result of this, to prevent interoperability issues, authors who register classes on such
WorkletGlobalScopes should make their code idempotent. That is, a method or set of
methods on the class should produce the same output given a particular input.
This specification uses the following techniques in order to encourage authors to write code in an idempotent way:
No reference to the global object is available (i.e., there is no counterpart to self on WorkletGlobalScope).
Code is loaded as a module script, which results in the code being executed
in strict mode and with no shared this referencing the global
proxy.
Together, these restrictions help prevent two different scripts from sharing state using properties of the global object.
Additionally, specifications which use worklets and intend to allow implementation-defined behavior must obey the following:
They must require user agents to always have at least two WorkletGlobalScope
instances per Worklet, and randomly assign a method or set of methods on a class to
a particular WorkletGlobalScope instance. These specifications may provide an
opt-out under memory constraints.
These specifications must allow user agents to create and destroy instances of their
WorkletGlobalScope subclasses at any time.
Some specifications which use worklets can invoke methods on a web-developer-provided class based on the state of the user agent. To increase concurrency between threads, a user agent may invoke a method speculatively, based on potential future states.
In these specifications, user agents might invoke such methods at any time, and with any arguments, not just ones corresponding to the current state of the user agent. The results of such speculative evaluations are not displayed immediately, but can be cached for use if the user agent state matches the speculated state. This can increase the concurrency between the user agent and worklet threads.
As a result of this, to prevent interoperability risks between user agents, authors who
register classes on such WorkletGlobalScopes should make their code stateless. That
is, the only effect of invoking a method should be its result, and not any side effects such as
updating mutable state.
The same techniques which encourage code idempotence also encourage authors to write stateless code.
This section is non-normative.
For these examples, we'll use a fake worklet. The Window object provides two
Worklet instances, which each run code in their own collection of
FakeWorkletGlobalScopes:
The fakeWorklet2 getter steps are to return
this's fake worklet 2.
The registerFake(type, classConstructor) method
steps are to set this's registered class constructors
map[type] to classConstructor.
This section is non-normative.
To load scripts into fake worklet 1, a web developer would write:
window. fakeWorklet1. addModule( 'script1.mjs' );
window. fakeWorklet1. addModule( 'script2.mjs' );
Note that which script finishes fetching and runs first is dependent on network timing: it
could be either script1.mjs or script2.mjs. This
generally won't matter for well-written scripts intended to be loaded in worklets, if they follow
the suggestions about preparing for speculative
evaluation.
If a web developer wants to perform a task only after the scripts have successfully run and loaded into some worklets, they could write:
Promise. all([
window. fakeWorklet1. addModule( 'script1.mjs' ),
window. fakeWorklet2. addModule( 'script2.mjs' )
]). then(() => {
// Do something which relies on those scripts being loaded.
});
Another important point about script-loading is that loaded scripts can be run in multiple
WorkletGlobalScopes per Worklet, as discussed in the section on code idempotence. In particular, the specification above
for fake worklet 1 and fake worklet 2 require this. So, consider a
scenario such as the following:
// script.mjs
console. log( "Hello from a FakeWorkletGlobalScope!" );
// app.mjs
window. fakeWorklet1. addModule( "script.mjs" );
This could result in output such as the following from a user agent's console:
[fakeWorklet1#1] Hello from a FakeWorkletGlobalScope!
[fakeWorklet1#4] Hello from a FakeWorkletGlobalScope!
[fakeWorklet1#2] Hello from a FakeWorkletGlobalScope!
[fakeWorklet1#3] Hello from a FakeWorkletGlobalScope!
If the user agent at some point decided to kill and restart the third instance of
FakeWorkletGlobalScope, the console would again print [fakeWorklet1#3] Hello from a FakeWorkletGlobalScope! when this occurs.
This section is non-normative.
Let's say that one of the intended usages of our fake worklet by web developers is to allow them to customize the highly-complex process of boolean negation. They might register their customization as follows:
// script.mjs
registerFake( 'negation-processor' , class {
process( arg) {
return ! arg;
}
});
// app.mjs
window. fakeWorklet1. addModule( "script.mjs" );
Subclasses of WorkletGlobalScope are used to create global objects wherein code loaded into a particular Worklet can
execute.
Each WorkletGlobalScope has an associated module map. It is a module map,
initially empty.
This section is non-normative.
Each WorkletGlobalScope is contained in its own worklet agent, which
has its corresponding event loop. However, in
practice, implementation of these agents and event loops is expected to be different from most
others.
A worklet agent exists for each WorkletGlobalScope since, in theory,
an implementation could use a separate thread for each WorkletGlobalScope instance,
and allowing this level of parallelism is best done using agents. However, because their
[[CanBlock]] value is false, there is no requirement that agents and threads are one-to-one. This
allows implementations the freedom to execute scripts loaded into a worklet on any thread,
including one running code from other agents with [[CanBlock]] of false, such as the thread of a
similar-origin window agent ("the main thread"). Contrast this with dedicated worker agents, whose true value for [[CanBlock]]
effectively requires them to get a dedicated operating system thread.
Worklet event loops are also somewhat special. They are only
used for tasks associated with addModule(), tasks wherein the user agent invokes
author-defined methods, and microtasks. Thus, even though the event loop processing model specifies that all event loops
run continuously, implementations can achieve observably-equivalent results using a simpler
strategy, which just invokes author-provided
methods and then relies on that process to perform a microtask checkpoint.
Worklet classSupport in all current engines.
The Worklet class provides the capability to add module scripts into its
associated WorkletGlobalScopes. The user agent can then create classes registered on
the WorkletGlobalScopes and invoke their methods.
Specifications that create Worklet instances must specify the following for a
given instance:
The lifetime of a Worklet has no special considerations; it is tied to the object
it belongs to, such as the Window.
The lifetime of a WorkletGlobalScope is, at a minimum, tied to the
Document whose worklet global
scopes contain it. In particular, destroying the
Document will terminate the
corresponding WorkletGlobalScope and allow it to be garbage-collected.
Additionally, user agents may, at any time, terminate a given WorkletGlobalScope, unless the specification defining
the corresponding worklet type says otherwise. For example, they might terminate them if the
worklet agent's event loop has no
tasks queued, or if the user agent has no pending operations
planning to make use of the worklet, or if the user agent detects abnormal operations such as
infinite loops or callbacks exceeding imposed time limits.
Finally, specifications for specific worklet types can give more specific details on when to
create WorkletGlobalScopes for a
given worklet type. For example, they might create them during specific processes that call upon
worklet code, as in the example.
Support in all current engines.
This section is non-normative.
This specification introduces two related mechanisms, similar to HTTP session cookies, for storing name-value pairs on the client side. [COOKIES]
The first is designed for scenarios where the user is carrying out a single transaction, but could be carrying out multiple transactions in different windows at the same time.
Cookies don't really handle this case well. For example, a user could be buying plane tickets in two different windows, using the same site. If the site used cookies to keep track of which ticket the user was buying, then as the user clicked from page to page in both windows, the ticket currently being purchased would "leak" from one window to the other, potentially causing the user to buy two tickets for the same flight without noticing.
To address this, this specification introduces the sessionStorage getter. Sites can add data to the session
storage, and it will be accessible to any page from the same site opened in that window.
The second storage mechanism is designed for storage that spans multiple windows, and lasts beyond the current session. In particular, web applications might wish to store megabytes of user data, such as entire user-authored documents or a user's mailbox, on the client side for performance reasons.
Again, cookies do not handle this case well, because they are transmitted with every request.
The localStorage getter is used to access a page's local
storage area.
Each site has its own separate storage area.
Support in all current engines.
Storage interfaceA Storage object has an associated:
local" or "session".
The supported property names on a Storage object storage
are the result of running get the keys on
storage's map.
sessionStorage getterlocalStorage getterStorageEvent interfaceSupport in all current engines.
The initStorageEvent(type, bubbles,
cancelable, key, oldValue, newValue, url,
storageArea) method must initialize the event in a manner analogous to the
similarly-named initEvent() method. [DOM]
A third-party advertiser (or any entity capable of getting content distributed to multiple sites) could use a unique identifier stored in its local storage area to track a user across multiple sessions, building a profile of the user's interests to allow for highly targeted advertising. In conjunction with a site that is aware of the user's real identity (for example an e-commerce site that requires authenticated credentials), this could allow oppressive groups to target individuals with greater accuracy than in a world with purely anonymous web usage.
There are a number of techniques that can be used to mitigate the risk of user tracking:
User agents may restrict access to the localStorage
objects to scripts originating at the domain of the active
document of the top-level traversable, for instance denying access to the
API for pages from other domains running in iframes.
User agents may, possibly in a manner configured by the user, automatically delete stored data after a period of time.
For example, a user agent could be configured to treat third-party local storage areas as session-only storage, deleting the data once the user had closed all the navigables that could access it.
This can restrict the ability of a site to track a user, as the site would then only be able to track the user across multiple sessions when they authenticate with the site itself (e.g. by making a purchase or logging in to a service).
However, this also reduces the usefulness of the API as a long-term storage mechanism. It can also put the user's data at risk, if the user does not fully understand the implications of data expiration.
If users attempt to protect their privacy by clearing cookies without also clearing data stored in the local storage area, sites can defeat those attempts by using the two features as redundant backup for each other. User agents should present the interfaces for clearing these in a way that helps users to understand this possibility and enables them to delete data in all persistent storage features simultaneously. [COOKIES]
User agents may allow sites to access session storage areas in an unrestricted manner, but require the user to authorize access to local storage areas.
User agents may record the origins of sites that contained content from third-party origins that caused data to be stored.
If this information is then used to present the view of data currently in persistent storage, it would allow the user to make informed decisions about which parts of the persistent storage to prune. Combined with a blocklist ("delete this data and prevent this domain from ever storing data again"), the user can restrict the use of persistent storage to sites that they trust.
User agents may allow users to share their persistent storage domain blocklists.
This would allow communities to act together to protect their privacy.
While these suggestions prevent trivial use of this API for user tracking, they do not block it altogether. Within a single domain, a site can continue to track the user during a session, and can then pass all this information to the third party along with any identifying information (names, credit card numbers, addresses) obtained by the site. If a third party cooperates with multiple sites to obtain such information, a profile can still be created.
However, user tracking is to some extent possible even with no cooperation from the user agent whatsoever, for instance by using session identifiers in URLs, a technique already commonly used for innocuous purposes but easily repurposed for user tracking (even retroactively). This information can then be shared with other sites, using visitors' IP addresses and other user-specific data (e.g. user-agent headers and configuration settings) to combine separate sessions into coherent user profiles.
User agents should treat persistently stored data as potentially sensitive; it's quite possible for emails, calendar appointments, health records, or other confidential documents to be stored in this mechanism.
To this end, user agents should ensure that when deleting data, it is promptly deleted from the underlying storage.
Because of the potential for DNS spoofing attacks, one cannot guarantee that a host claiming to be in a certain domain really is from that domain. To mitigate this, pages can use TLS. Pages using TLS can be sure that only the user, software working on behalf of the user, and other pages using TLS that have certificates identifying them as being from the same domain, can access their storage areas.
Different authors sharing one host name, for example users hosting content on the now defunct
geocities.com, all share one local storage object. There is no feature to
restrict the access by pathname. Authors on shared hosts are therefore urged to avoid using these
features, as it would be trivial for other authors to read the data and overwrite it.
The two primary risks when implementing these persistent storage features are letting hostile sites read information from other domains, and letting hostile sites write information that is then read from other domains.
Letting third-party sites read data that is not supposed to be read from their domain causes information leakage. For example, a user's shopping wishlist on one domain could be used by another domain for targeted advertising; or a user's work-in-progress confidential documents stored by a word-processing site could be examined by the site of a competing company.
Letting third-party sites write data to the persistent storage of other domains can result in information spoofing, which is equally dangerous. For example, a hostile site could add items to a user's wishlist; or a hostile site could set a user's session identifier to a known ID that the hostile site can then use to track the user's actions on the victim site.
Thus, strictly following the origin model described in this specification is important for user security.
This section only applies to documents, authoring tools, and markup generators. In particular, it does not apply to conformance checkers; conformance checkers must use the requirements given in the next section ("parsing HTML documents").
Documents must consist of the following parts, in the given order:
html element.The various types of content mentioned above are described in the next few sections.
In addition, there are some restrictions on how character encoding declarations are to be serialized, as discussed in the section on that topic.
Many strings in the HTML syntax (e.g. the names of elements and their attributes) are case-insensitive, but only for ASCII upper alphas and ASCII lower alphas. For convenience, in this section this is just referred to as "case-insensitive".
A DOCTYPE must consist of the following components, in this order:
<!DOCTYPE".html".The DOCTYPE legacy string should not be used unless the document is generated from a system that cannot output the shorter string.
The contents of the element must be placed between just after the start tag (which might be implied, in certain cases) and just before the end tag (which again, might be implied in certain cases). The exact allowed contents of each individual element depend on the content model of that element, as described earlier in this specification. Elements must not contain content that their content model disallows. In addition to the restrictions placed on the contents by those content models, however, the five types of elements have additional syntactic requirements.
Void elements can't have any contents (since there's no end tag, no content can be put between the start tag and the end tag).
The template element can have
template contents, but such template contents are not children of the
template element itself. Instead, they are stored in a DocumentFragment
associated with a different Document — without a browsing context — so
as to avoid the template contents interfering with the main Document.
The markup for the template contents of a template element is placed
just after the template element's start tag and just before template
element's end tag (as with other elements), and may consist of any text, character references, elements, and comments, but
the text must not contain the character U+003C LESS-THAN SIGN (<) or an ambiguous ampersand.
Raw text elements can have text, though it has restrictions described below.
Escapable raw text elements can have text and character references, but the text must not contain an ambiguous ampersand. There are also further restrictions described below.
Foreign elements whose start tag is marked as self-closing can't have any contents (since, again, as there's no end tag, no content can be put between the start tag and the end tag). Foreign elements whose start tag is not marked as self-closing can have text, character references, CDATA sections, other elements, and comments, but the text must not contain the character U+003C LESS-THAN SIGN (<) or an ambiguous ampersand.
Normal elements can have text, character references, other elements, and comments, but the text must not contain the character U+003C LESS-THAN SIGN (<) or an ambiguous ampersand. Some normal elements also have yet more restrictions on what content they are allowed to hold, beyond the restrictions imposed by the content model and those described in this paragraph. Those restrictions are described below.
Tags contain a tag name, giving the element's name. HTML elements all have names that only use ASCII alphanumerics. In the HTML syntax, tag names, even those for foreign elements, may be written with any mix of lower- and uppercase letters that, when converted to all-lowercase, matches the element's tag name; tag names are case-insensitive.
Attributes can be specified in four different ways:
Just the attribute name. The value is implicitly the empty string.
If an attribute using the empty attribute syntax is to be followed by another attribute, then there must be ASCII whitespace separating the two.
The attribute name, followed by zero or more ASCII whitespace, followed by a single U+003D EQUALS SIGN character, followed by zero or more ASCII whitespace, followed by the attribute value, which, in addition to the requirements given above for attribute values, must not contain any literal ASCII whitespace, any U+0022 QUOTATION MARK characters ("), U+0027 APOSTROPHE characters ('), U+003D EQUALS SIGN characters (=), U+003C LESS-THAN SIGN characters (<), U+003E GREATER-THAN SIGN characters (>), or U+0060 GRAVE ACCENT characters (`), and must not be the empty string.
If an attribute using the unquoted attribute syntax is to be followed by another attribute or by the optional U+002F SOLIDUS character (/) allowed in step 6 of the start tag syntax above, then there must be ASCII whitespace separating the two.
The attribute name, followed by zero or more ASCII whitespace, followed by a single U+003D EQUALS SIGN character, followed by zero or more ASCII whitespace, followed by a single U+0027 APOSTROPHE character ('), followed by the attribute value, which, in addition to the requirements given above for attribute values, must not contain any literal U+0027 APOSTROPHE characters ('), and finally followed by a second single U+0027 APOSTROPHE character (').
If an attribute using the single-quoted attribute syntax is to be followed by another attribute, then there must be ASCII whitespace separating the two.
The attribute name, followed by zero or more ASCII whitespace, followed by a single U+003D EQUALS SIGN character, followed by zero or more ASCII whitespace, followed by a single U+0022 QUOTATION MARK character ("), followed by the attribute value, which, in addition to the requirements given above for attribute values, must not contain any literal U+0022 QUOTATION MARK characters ("), and finally followed by a second single U+0022 QUOTATION MARK character (").
If an attribute using the double-quoted attribute syntax is to be followed by another attribute, then there must be ASCII whitespace separating the two.
There must never be two or more attributes on the same start tag whose names are an ASCII case-insensitive match for each other.
When a foreign element has one of the namespaced attributes given by the local name and namespace of the first and second cells of a row from the following table, it must be written using the name given by the third cell from the same row.
| Local name | Namespace | Attribute name |
|---|---|---|
actuate | XLink namespace | xlink:actuate
|
arcrole | XLink namespace | xlink:arcrole
|
href | XLink namespace | xlink:href
|
role | XLink namespace | xlink:role
|
show | XLink namespace | xlink:show
|
title | XLink namespace | xlink:title
|
type | XLink namespace | xlink:type
|
lang | XML namespace | xml:lang
|
space | XML namespace | xml:space
|
xmlns | XMLNS namespace | xmlns
|
xlink | XMLNS namespace | xmlns:xlink
|
No other namespaced attribute can be expressed in the HTML syntax.
An html element's start tag may be omitted
if the first thing inside the html element is not a comment.
An html element's end tag may be omitted if
the html element is not immediately followed by a comment.
A head element's start tag may be omitted if
the element is empty, or if the first thing inside the head element is an
element.
A head element's end tag may be omitted if
the head element is not immediately followed by ASCII whitespace or a
comment.
A body element's start tag may be omitted
if the element is empty, or if the first thing inside the body element is not
ASCII whitespace or a comment, except if the
first thing inside the body element is a meta, noscript,
link, script, style, or template element.
A body element's end tag may be omitted if the
body element is not immediately followed by a comment.
An li element's end tag may be omitted if the
li element is immediately followed by another li element or if there is
no more content in the parent element.
A dt element's end tag may be omitted if the
dt element is immediately followed by another dt element or a
dd element.
A dd element's end tag may be omitted if the
dd element is immediately followed by another dd element or a
dt element, or if there is no more content in the parent element.
A p element's end tag may be omitted if the
p element is immediately followed by an address, article,
aside, blockquote, details, dialog,
div, dl, fieldset, figcaption,
figure, footer, form, h1, h2,
h3, h4, h5, h6, header,
hgroup, hr, main, menu, nav,
ol, p, pre, search, section,
table, or ul element, or if there is no more content in the parent
element and the parent element is an HTML element that is not
an a, audio, del, ins, map,
noscript, or video element, or an autonomous custom
element.
An rt element's end tag may be omitted if the
rt element is immediately followed by an rt or rp element,
or if there is no more content in the parent element.
An rp element's end tag may be omitted if the
rp element is immediately followed by an rt or rp element,
or if there is no more content in the parent element.
An optgroup element's end tag may be omitted
if the optgroup element is
immediately followed by another optgroup element, if it is immediately followed by an
hr element, or if there is no more content in the parent
element.
An option element's end tag may be omitted if
the option element is immediately followed by another option element, if
it is immediately followed by an optgroup element, if it is immediately followed by
an hr element, or if there is no more content in the parent element.
A colgroup element's start tag may be
omitted if the first thing inside the colgroup element is a col element,
and if the element is not immediately preceded by another colgroup element whose
end tag has been omitted. (It can't be omitted if the element
is empty.)
A colgroup element's end tag may be omitted
if the colgroup element is not immediately followed by ASCII whitespace
or a comment.
A caption element's end tag may be omitted if
the caption element is not immediately followed by ASCII whitespace or a
comment.
A thead element's end tag may be omitted if
the thead element is immediately followed by a tbody or
tfoot element.
A tbody element's start tag may be omitted
if the first thing inside the tbody element is a tr element, and if the
element is not immediately preceded by a tbody, thead, or
tfoot element whose end tag has been omitted. (It
can't be omitted if the element is empty.)
A tbody element's end tag may be omitted if
the tbody element is immediately followed by a tbody or
tfoot element, or if there is no more content in the parent element.
A tfoot element's end tag may be omitted if
there is no more content in the parent element.
A tr element's end tag may be omitted if the
tr element is immediately followed by another tr element, or if there is
no more content in the parent element.
A td element's end tag may be omitted if the
td element is immediately followed by a td or th element,
or if there is no more content in the parent element.
A th element's end tag may be omitted if the
th element is immediately followed by a td or th element,
or if there is no more content in the parent element.
However, a start tag must never be omitted if it has any attributes.
For historical reasons, certain elements have extra restrictions beyond even the restrictions given by their content model.
A table element must not contain tr elements, even though these
elements are technically allowed inside table elements according to the content
models described in this specification. (If a tr element is put inside a
table in the markup, it will in fact imply a tbody start tag before
it.)
A single newline may be placed immediately after the start tag of pre and textarea elements.
This does not affect the processing of the element. The otherwise optional newline must be included if the element's contents
themselves start with a newline (because otherwise the
leading newline in the contents would be treated like the optional newline, and ignored).
The text in raw text and escapable raw text
elements must not contain any occurrences of the string "</"
(U+003C LESS-THAN SIGN, U+002F SOLIDUS) followed by characters that case-insensitively match the
tag name of the element followed by one of U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED
(LF), U+000C FORM FEED (FF), U+000D CARRIAGE RETURN (CR), U+0020 SPACE, U+003E GREATER-THAN SIGN
(>), or U+002F SOLIDUS (/).
Text is allowed inside elements, attribute values, and comments. Extra constraints are placed on what is and what is not allowed in text based on where the text is to be put, as described in the other sections.
Where character references are allowed, a character reference of a U+000A LINE FEED (LF) character (but not a U+000D CARRIAGE RETURN (CR) character) also represents a newline.
Character references must start with a U+0026 AMPERSAND character (&). Following this, there are three possible kinds of character references:
The numeric character reference forms described above are allowed to reference any code point excluding U+000D CR, noncharacters, and controls other than ASCII whitespace.
An ambiguous ampersand is a U+0026 AMPERSAND character (&) that is followed by one or more ASCII alphanumerics, followed by a U+003B SEMICOLON character (;), where these characters do not match any of the names given in the named character references section.
This section only applies to user agents, data mining tools, and conformance checkers.
For the purposes of conformance checkers, if a resource is determined to be in the HTML syntax, then it is an HTML document.
The input to the HTML parsing process consists of a stream of code
points, which is passed through a tokenization stage followed by a tree
construction stage. The output is a Document object.
In the common case, the data handled by the tokenization stage comes from the network, but
it can also come from script running in the user
agent, e.g. using the document.write() API.
There is only one set of states for the tokenizer stage and the tree construction stage, but the tree construction stage is reentrant, meaning that while the tree construction stage is handling one token, the tokenizer might be resumed, causing further tokens to be emitted and processed before the first token's processing is complete.
To handle these cases, parsers have a script nesting level, which must be initially set to zero, and a parser pause flag, which must be initially set to false.
This specification defines the parsing rules for HTML documents, whether they are syntactically correct or not. Certain points in the parsing algorithm are said to be parse errors. The error handling for parse errors is well-defined (that's the processing rules described throughout this specification), but user agents, while parsing an HTML document, may abort the parser at the first parse error that they encounter for which they do not wish to apply the rules described in this specification.
Conformance checkers must report at least one parse error condition to the user if one or more parse error conditions exist in the document and must not report parse error conditions if none exist in the document. Conformance checkers may report more than one parse error condition if more than one parse error condition exists in the document.
Some parse errors have dedicated codes outlined in the table below that should be used by conformance checkers in reports.
Error descriptions in the table below are non-normative.
| Code | Description |
|---|---|
| abrupt-closing-of-empty-comment | This error occurs if the parser encounters an empty comment that is abruptly closed by a U+003E (>) code
point (i.e., |
| abrupt-doctype-public-identifier | This error occurs if the parser encounters a U+003E (>) code point in the
DOCTYPE public identifier (e.g., |
| abrupt-doctype-system-identifier | This error occurs if the parser encounters a U+003E (>) code point in the
DOCTYPE system identifier (e.g., |
| absence-of-digits-in-numeric-character-reference | This error occurs if the parser encounters a numeric character reference that doesn't contain any digits (e.g., |
| cdata-in-html-content | This error occurs if the parser encounters a CDATA
section outside of foreign content (SVG or MathML). The parser treats such CDATA
sections (including leading " |
| character-reference-outside-unicode-range | This error occurs if the parser encounters a numeric character reference that references a code point that is greater than the valid Unicode range. The parser resolves such a character reference to a U+FFFD REPLACEMENT CHARACTER. |
| control-character-in-input-stream | This error occurs if the input stream contains a control code point that is not ASCII whitespace or U+0000 NULL. Such code points are parsed as-is and usually, where parsing rules don't apply any additional restrictions, make their way into the DOM. |
| control-character-reference | This error occurs if the parser encounters a numeric character reference that references a control code point that is not ASCII whitespace or is a U+000D CARRIAGE RETURN. The parser resolves such character references as-is except C1 control references that are replaced according to the numeric character reference end state. |
| duplicate-attribute | This error occurs if the parser encounters an attribute in a tag that already has an attribute with the same name. The parser ignores all such duplicate occurrences of the attribute. |
| end-tag-with-attributes | This error occurs if the parser encounters an end tag with attributes. Attributes in end tags are ignored and do not make their way into the DOM. |
| end-tag-with-trailing-solidus | This error occurs if the parser encounters an end
tag that has a U+002F (/) code point right before the closing U+003E (>)
code point (e.g., |
| eof-before-tag-name | This error occurs if the parser encounters the end of the input stream
where a tag name is expected. In this case the parser treats the beginning of a start tag (i.e., |
| eof-in-cdata | This error occurs if the parser encounters the end of the input stream in a CDATA section. The parser treats such CDATA sections as if they are closed immediately before the end of the input stream. |
| eof-in-comment | This error occurs if the parser encounters the end of the input stream in a comment. The parser treats such comments as if they are closed immediately before the end of the input stream. |
| eof-in-doctype | This error occurs if the parser encounters the end of the input stream in a DOCTYPE. In such a case, if the DOCTYPE is correctly placed as a
document preamble, the parser sets the |
| eof-in-script-html-comment-like-text |
This error occurs if the parser encounters the end of the input stream in text
that resembles an HTML comment inside
|
| eof-in-tag | This error occurs if the parser encounters the end of the input stream in a
start tag or an end
tag (e.g., |
| incorrectly-closed-comment | This error occurs if the parser encounters a comment that is closed by the " |
| incorrectly-opened-comment |
This error occurs if the parser encounters the " |
| invalid-character-sequence-after-doctype-name | This error occurs if the parser encounters any code point sequence other
than " |
| invalid-first-character-of-tag-name |
This error occurs if the parser encounters a code point that is not an ASCII alpha where first code point of a start tag name or an end tag name is expected. If a start tag was expected such code point and a preceding U+003C (<) is treated as text content, and all content that follows is treated as markup. Whereas, if an end tag was expected, such code point and all content that follows up to a U+003E (>) code point (if present) or to the end of the input stream is treated as a comment. |
| missing-attribute-value | This error occurs if the parser encounters a U+003E (>) code point where an
attribute value is expected (e.g., |
| missing-doctype-name | This error occurs if the parser encounters a DOCTYPE that is missing a name (e.g., |
| missing-doctype-public-identifier | This error occurs if the parser encounters a U+003E (>) code point where
start of the DOCTYPE public identifier is expected (e.g.,
|
| missing-doctype-system-identifier | This error occurs if the parser encounters a U+003E (>) code point where
start of the DOCTYPE system identifier is expected (e.g.,
|
| missing-end-tag-name | This error occurs if the parser encounters a U+003E (>) code point where an
end tag name is expected, i.e., |
| missing-quote-before-doctype-public-identifier | This error occurs if the parser encounters the DOCTYPE public identifier that is not preceded by a quote (e.g.,
|
| missing-quote-before-doctype-system-identifier | This error occurs if the parser encounters the DOCTYPE system identifier that is not preceded by a quote (e.g.,
|
| missing-semicolon-after-character-reference |
This error occurs if the parser encounters a character reference that is not terminated by a U+003B (;) code point. Usually the parser behaves as if character reference is terminated by the U+003B (;) code point; however, there are some ambiguous cases in which the parser includes subsequent code points in the character reference. |
| missing-whitespace-after-doctype-public-keyword | This error occurs if the parser encounters a DOCTYPE whose " |
| missing-whitespace-after-doctype-system-keyword | This error occurs if the parser encounters a DOCTYPE whose " |
| missing-whitespace-before-doctype-name | This error occurs if the parser encounters a DOCTYPE whose " |
| missing-whitespace-between-attributes | This error occurs if the parser encounters attributes that are not separated by ASCII
whitespace (e.g., |
| missing-whitespace-between-doctype-public-and-system-identifiers | This error occurs if the parser encounters a DOCTYPE whose public and system identifiers are not separated by ASCII whitespace. In this case the parser behaves as if ASCII whitespace is present. |
| nested-comment | This error occurs if the parser encounters a nested comment (e.g., |
| noncharacter-character-reference | This error occurs if the parser encounters a numeric character reference that references a noncharacter. The parser resolves such character references as-is. |
| noncharacter-in-input-stream | This error occurs if the input stream contains a noncharacter. Such code points are parsed as-is and usually, where parsing rules don't apply any additional restrictions, make their way into the DOM. |
| non-void-html-element-start-tag-with-trailing-solidus |
This error occurs if the parser encounters a start tag for an element that is not in the list of void elements or is not a part of foreign content (i.e., not an SVG or MathML element) that has a U+002F (/) code point right before the closing U+003E (>) code point. The parser behaves as if the U+002F (/) is not present. |
| null-character-reference | This error occurs if the parser encounters a numeric character reference that references a U+0000 NULL code point. The parser resolves such character references to a U+FFFD REPLACEMENT CHARACTER. |
| surrogate-character-reference | This error occurs if the parser encounters a numeric character reference that references a surrogate. The parser resolves such character references to a U+FFFD REPLACEMENT CHARACTER. |
| surrogate-in-input-stream |
This error occurs if the input stream contains a surrogate. Such code points are parsed as-is and usually, where parsing rules don't apply any additional restrictions, make their way into the DOM. |
| unexpected-character-after-doctype-system-identifier | This error occurs if the parser encounters any code points other than ASCII whitespace or closing U+003E (>) after the DOCTYPE system identifier. The parser ignores these code points. |
| unexpected-character-in-attribute-name |
This error occurs if the parser encounters a U+0022 ("), U+0027 ('), or U+003C (<) code point in an attribute name. The parser includes such code points in the attribute name. |
| unexpected-character-in-unquoted-attribute-value |
This error occurs if the parser encounters a U+0022 ("), U+0027 ('), U+003C (<), U+003D (=), or U+0060 (`) code point in an unquoted attribute value. The parser includes such code points in the attribute value. |
| unexpected-equals-sign-before-attribute-name |
This error occurs if the parser encounters a U+003D (=) code point before an attribute name. In this case the parser treats U+003D (=) as the first code point of the attribute name. |
| unexpected-null-character | This error occurs if the parser encounters a U+0000 NULL code point in the input stream in certain positions. In general, such code points are either ignored or, for security reasons, replaced with a U+FFFD REPLACEMENT CHARACTER. |
| unexpected-question-mark-instead-of-tag-name |
This error occurs if the parser encounters a U+003F (?) code point where first code point of a start tag name is expected. The U+003F (?) and all content that follows up to a U+003E (>) code point (if present) or to the end of the input stream is treated as a comment. |
| unexpected-solidus-in-tag | This error occurs if the parser encounters a U+002F (/) code point that is
not a part of a quoted attribute value and not
immediately followed by a U+003E (>) code point in a tag (e.g., |
| unknown-named-character-reference | This error occurs if the parser encounters an ambiguous ampersand. In this case the parser doesn't resolve the character reference. |
The stream of code points that comprises the input to the tokenization stage will be initially seen by the user agent as a stream of bytes (typically coming over the network or from the local file system). The bytes encode the actual characters according to a particular character encoding, which the user agent uses to decode the bytes into characters.
Usually, the encoding sniffing algorithm defined below is used to determine the character encoding.
Given a character encoding, the bytes in the input byte stream must be converted to characters for the tokenizer's input stream, by passing the input byte stream and character encoding to decode.
When the HTML parser is decoding an input byte stream, it uses a character encoding and a confidence. The confidence is either tentative, certain, or irrelevant. The encoding used, and whether the confidence in that encoding is tentative or certain, is used during the parsing to determine whether to change the encoding. If no encoding is necessary, e.g. because the parser is operating on a Unicode stream and doesn't have to use a character encoding at all, then the confidence is irrelevant.
When the HTML parser is to operate on an input byte stream that has a known definite encoding, then the character encoding is that encoding and the confidence is certain.
In some cases, it might be impractical to unambiguously determine the encoding before parsing the document. Because of this, this specification provides for a two-pass mechanism with an optional pre-scan. Implementations are allowed, as described below, to apply a simplified parsing algorithm to whatever bytes they have available before beginning to parse the document. Then, the real parser is started, using a tentative encoding derived from this pre-parse and other out-of-band metadata. If, while the document is being loaded, the user agent discovers a character encoding declaration that conflicts with this information, then the parser can get reinvoked to perform a parse of the document with the real encoding.
The document's character encoding must immediately be set to the value returned from this algorithm, at the same time as the user agent uses the returned value to select the decoder to use for the input byte stream.
When an algorithm requires a user agent to prescan a byte stream to determine its encoding, given some defined end condition, then it must run the following steps. If at any point during these steps (including during instances of the get an attribute algorithm invoked by this one) the user agent either runs out of bytes (meaning the position pointer created in the first step below goes beyond the end of the byte stream obtained so far) or reaches its end condition, then abort the prescan a byte stream to determine its encoding algorithm and return the result get an XML encoding applied to the same bytes that the prescan a byte stream to determine its encoding algorithm was applied to. Otherwise, these steps will return a character encoding.
Let fallback encoding be null.
Let position be a pointer to a byte in the input byte stream, initially pointing at the first byte.
Prescan for UTF-16 XML declarations: If position points to:
Loop: If position points to:
<!--`)Advance the position pointer so that it points at the first 0x3E byte which is preceded by two 0x2D bytes (i.e. at the end of an ASCII '-->' sequence) and comes after the 0x3C byte that was found. (The two 0x2D bytes can be the same as those in the '<!--' sequence.)
Advance the position pointer so that it points at the next 0x09, 0x0A, 0x0C, 0x0D, 0x20, or 0x2F byte (the one in sequence of characters matched above).
Let attribute list be an empty list of strings.
Let got pragma be false.
Let need pragma be null.
Let charset be the null value (which, for the purposes of this algorithm, is distinct from an unrecognized encoding or the empty string).
Attributes: Get an attribute and its value. If no attribute was sniffed, then jump to the processing step below.
If the attribute's name is already in attribute list, then return to the step labeled attributes.
Add the attribute's name to attribute list.
Run the appropriate step from the following list, if one applies:
http-equiv"If the attribute's value is "content-type", then set got pragma to true.
content"Apply the algorithm for extracting a character encoding from a
meta element, giving the attribute's value as the string to parse. If a
character encoding is returned, and if charset is still set to null,
let charset be the encoding returned, and set need
pragma to true.
charset"Let charset be the result of getting an encoding from the attribute's value, and set need pragma to false.
Return to the step labeled attributes.
Processing: If need pragma is null, then jump to the step below labeled next byte.
If need pragma is true but got pragma is false, then jump to the step below labeled next byte.
If charset is failure, then jump to the step below labeled next byte.
If charset is UTF-16BE/LE, then set charset to UTF-8.
If charset is x-user-defined, then set charset to windows-1252.
Return charset.
Advance the position pointer so that it points at the next 0x09 (HT), 0x0A (LF), 0x0C (FF), 0x0D (CR), 0x20 (SP), or 0x3E (>) byte.
Repeatedly get an attribute until no further attributes can be found, then jump to the step below labeled next byte.
<!`)</`)<?`)Advance the position pointer so that it points at the first 0x3E byte (>) that comes after the 0x3C byte that was found.
Do nothing with that byte.
For the sake of interoperability, user agents should not use a pre-scan algorithm that returns different results than the one described above. (But, if you do, please at least let us know, so that we can improve this algorithm and benefit everyone...)
User agents must support the encodings defined in Encoding, including, but not limited to, UTF-8, ISO-8859-2, ISO-8859-7, ISO-8859-8, windows-874, windows-1250, windows-1251, windows-1252, windows-1254, windows-1255, windows-1256, windows-1257, windows-1258, GBK, Big5, ISO-2022-JP, Shift_JIS, EUC-KR, UTF-16BE, UTF-16LE, UTF-16BE/LE, and x-user-defined. User agents must not support other encodings.
Any occurrences of surrogates are surrogate-in-input-stream parse errors. Any occurrences of noncharacters are noncharacter-in-input-stream parse errors and any occurrences of controls other than ASCII whitespace and U+0000 NULL characters are control-character-in-input-stream parse errors.
Before the tokenization stage, the input stream must be preprocessed by normalizing newlines. Thus, newlines in HTML DOMs are represented by U+000A LF characters, and there are never any U+000D CR characters in the input to the tokenization stage.
The next input character is the first character in the input stream that has not yet been consumed or explicitly ignored by the requirements in this section. Initially, the next input character is the first character in the input. The current input character is the last character to have been consumed.
The "EOF" character in the tables below is a conceptual character representing the end of the
input stream. If the parser is a script-created parser, then the end of
the input stream is reached when an explicit "EOF" character (inserted by
the document.close() method) is consumed. Otherwise, the
"EOF" character is not a real character in the stream, but rather the lack of any further
characters.
Initially, the insertion mode is "initial". It can change to "before html", "before head", "in head", "in head noscript", "after head", "in body", "text", "in table", "in table text", "in caption", "in column group", "in table body", "in row", "in cell", "in select", "in select in table", "in template", "after body", "in frameset", "after frameset", "after after body", and "after after frameset" during the course of the parsing, as described in the tree construction stage. The insertion mode affects how tokens are processed and whether CDATA sections are supported.
Similarly, to parse nested template elements, a stack of template insertion
modes is used. It is initially empty. The current template insertion mode is the
insertion mode that was most recently added to the stack of template insertion modes.
The algorithms in the sections below will push insertion modes onto this stack, meaning
that the specified insertion mode is to be added to the stack, and pop insertion modes from
the stack, which means that the most recently added insertion mode must be removed from the
stack.
The html node, however it is created, is the topmost node of the stack. It only
gets popped off the stack when the parser finishes.
When the current node is removed from the stack of open elements, process internal resource links given the current node's node document.
Elements in the stack of open elements fall into the following categories:
The following elements have varying levels of special parsing rules: HTML's
address, applet, area, article,
aside, base, basefont, bgsound,
blockquote, body, br, button,
caption, center, col, colgroup,
dd, details, dir, div, dl,
dt, embed, fieldset, figcaption,
figure, footer, form, frame,
frameset, h1, h2, h3, h4,
h5, h6, head, header, hgroup,
hr, html, iframe,
img, input, keygen, li, link,
listing, main, marquee, menu,
meta, nav, noembed, noframes,
noscript, object, ol, p,
param, plaintext, pre, script,
search, section, select, source,
style, summary, table, tbody,
td, template, textarea, tfoot,
th, thead, title, tr, track,
ul, wbr, xmp; MathML mi,
MathML mo, MathML mn, MathML
ms, MathML mtext, and MathML
annotation-xml; and SVG foreignObject, SVG
desc, and SVG title.
The following HTML elements are those that end up in the list of active formatting
elements: a, b, big, code,
em, font, i, nobr, s,
small, strike, strong, tt, and
u.
All other elements found while parsing an HTML document.
Nothing happens if at any time any of the elements in the stack of open elements
are moved to a new location in, or removed from, the Document tree. In particular,
the stack is not changed in this situation. This can cause, amongst other strange effects, content
to be appended to nodes that are no longer in the DOM.
In addition, each element in the list of active formatting elements is associated with the token for which it was created, so that further elements can be created for that token if necessary.
This has the effect of reopening all the formatting elements that were opened in the current body, cell, or caption (whichever is youngest) that haven't been explicitly closed.
Initially, the head element pointer and the form element pointer are both null.
Once a head element has been parsed (whether implicitly or explicitly) the
head element pointer gets set to point to this node.
The form element pointer points to the last
form element that was opened and whose end tag has not yet been seen. It is used to
make form controls associate with forms in the face of dramatically bad markup, for historical
reasons. It is ignored inside template elements.
The frameset-ok flag is set to "ok" when the parser is created. It is set to "not ok" after certain tokens are seen.
Implementations must act as if they used the following state machine to tokenize HTML. The state machine must start in the data state. Most states consume a single character, which may have various side-effects, and either switches the state machine to a new state to reconsume the current input character, or switches it to a new state to consume the next character, or stays in the same state to consume the next character. Some states have more complicated behavior and can consume several characters before switching to another state. In some cases, the tokenizer state is also changed by the tree construction stage.
The exact behavior of certain states depends on the insertion mode and the stack of open elements. Certain states also use a temporary buffer to track progress, and the character reference state uses a return state to return to the state it was invoked from.
The output of the tokenization step is a series of zero or more of the following tokens: DOCTYPE, start tag, end tag, comment, character, end-of-file. DOCTYPE tokens have a name, a public identifier, a system identifier, and a force-quirks flag. When a DOCTYPE token is created, its name, public identifier, and system identifier must be marked as missing (which is a distinct state from the empty string), and the force-quirks flag must be set to off (its other state is on). Start and end tag tokens have a tag name, a self-closing flag, and a list of attributes, each of which has a name and a value. When a start or end tag token is created, its self-closing flag must be unset (its other state is that it be set), and its attributes list must be empty. Comment and character tokens have data.
When a token is emitted, it must immediately be handled by the tree construction
stage. The tree construction stage can affect the state of the tokenization stage, and can insert
additional characters into the stream. (For example, the script element can result in
scripts executing and using the dynamic markup insertion APIs to insert characters
into the stream being tokenized.)
When an end tag token is emitted with attributes, that is an end-tag-with-attributes parse error.
When an end tag token is emitted with its self-closing flag set, that is an end-tag-with-trailing-solidus parse error.
Before each step of the tokenizer, the user agent must first check the parser pause flag. If it is true, then the tokenizer must abort the processing of any nested invocations of the tokenizer, yielding control back to the caller.
The tokenizer state machine consists of the states defined in the following subsections.
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
script", then switch to the script data double escaped state.
Otherwise, switch to the script data escaped state. Emit the current input
character as a character token.Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
script", then switch to the script data escaped state. Otherwise,
switch to the script data double escaped state. Emit the current input
character as a character token.Consume the next input character:
Consume the next input character:
When the user agent leaves the attribute name state (and before emitting the tag token, if appropriate), the complete attribute's name must be compared to the other attributes on the same token; if there is already an attribute on the token with the exact same name, then this is a duplicate-attribute parse error and the new attribute must be removed from the token.
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
If the next few characters are:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
If the six characters starting from the current input character are an ASCII case-insensitive match for the word "PUBLIC", then consume those characters and switch to the after DOCTYPE public keyword state.
Otherwise, if the six characters starting from the current input character are an ASCII case-insensitive match for the word "SYSTEM", then consume those characters and switch to the after DOCTYPE system keyword state.
Otherwise, this is an invalid-character-sequence-after-doctype-name parse error. Set the current DOCTYPE token's force-quirks flag to on. Reconsume in the bogus DOCTYPE state.
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Set the temporary buffer to the empty string. Append a U+0026 AMPERSAND (&) character to the temporary buffer. Consume the next input character:
Consume the maximum number of characters possible, where the consumed characters are one of the identifiers in the first column of the named character references table. Append each character to the temporary buffer when it's consumed.
If the character reference was consumed as part of an attribute, and the last character matched is not a U+003B SEMICOLON character (;), and the next input character is either a U+003D EQUALS SIGN character (=) or an ASCII alphanumeric, then, for historical reasons, flush code points consumed as a character reference and switch to the return state.
Otherwise:
If the last character matched is not a U+003B SEMICOLON character (;), then this is a missing-semicolon-after-character-reference parse error.
Set the temporary buffer to the empty string. Append one or two characters corresponding to the character reference name (as given by the second column of the named character references table) to the temporary buffer.
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Consume the next input character:
Check the character reference code:
If the number is 0x00, then this is a null-character-reference parse error. Set the character reference code to 0xFFFD.
If the number is greater than 0x10FFFF, then this is a character-reference-outside-unicode-range parse error. Set the character reference code to 0xFFFD.
If the number is a surrogate, then this is a surrogate-character-reference parse error. Set the character reference code to 0xFFFD.
If the number is a noncharacter, then this is a noncharacter-character-reference parse error.
If the number is 0x0D, or a control that's not ASCII whitespace, then this is a control-character-reference parse error. If the number is one of the numbers in the first column of the following table, then find the row with that number in the first column, and set the character reference code to the number in the second column of that row.
| Number | Code point | |
|---|---|---|
| 0x80 | 0x20AC | EURO SIGN (€) |
| 0x82 | 0x201A | SINGLE LOW-9 QUOTATION MARK (‚) |
| 0x83 | 0x0192 | LATIN SMALL LETTER F WITH HOOK (ƒ) |
| 0x84 | 0x201E | DOUBLE LOW-9 QUOTATION MARK („) |
| 0x85 | 0x2026 | HORIZONTAL ELLIPSIS (…) |
| 0x86 | 0x2020 | DAGGER (†) |
| 0x87 | 0x2021 | DOUBLE DAGGER (‡) |
| 0x88 | 0x02C6 | MODIFIER LETTER CIRCUMFLEX ACCENT (ˆ) |
| 0x89 | 0x2030 | PER MILLE SIGN (‰) |
| 0x8A | 0x0160 | LATIN CAPITAL LETTER S WITH CARON (Š) |
| 0x8B | 0x2039 | SINGLE LEFT-POINTING ANGLE QUOTATION MARK (‹) |
| 0x8C | 0x0152 | LATIN CAPITAL LIGATURE OE (Œ) |
| 0x8E | 0x017D | LATIN CAPITAL LETTER Z WITH CARON (Ž) |
| 0x91 | 0x2018 | LEFT SINGLE QUOTATION MARK (‘) |
| 0x92 | 0x2019 | RIGHT SINGLE QUOTATION MARK (’) |
| 0x93 | 0x201C | LEFT DOUBLE QUOTATION MARK (“) |
| 0x94 | 0x201D | RIGHT DOUBLE QUOTATION MARK (”) |
| 0x95 | 0x2022 | BULLET (•) |
| 0x96 | 0x2013 | EN DASH (–) |
| 0x97 | 0x2014 | EM DASH (—) |
| 0x98 | 0x02DC | SMALL TILDE (˜) |
| 0x99 | 0x2122 | TRADE MARK SIGN (™) |
| 0x9A | 0x0161 | LATIN SMALL LETTER S WITH CARON (š) |
| 0x9B | 0x203A | SINGLE RIGHT-POINTING ANGLE QUOTATION MARK (›) |
| 0x9C | 0x0153 | LATIN SMALL LIGATURE OE (œ) |
| 0x9E | 0x017E | LATIN SMALL LETTER Z WITH CARON (ž) |
| 0x9F | 0x0178 | LATIN CAPITAL LETTER Y WITH DIAERESIS (Ÿ) |
Set the temporary buffer to the empty string. Append a code point equal to the character reference code to the temporary buffer. Flush code points consumed as a character reference. Switch to the return state.
The input to the tree construction stage is a sequence of tokens from the
tokenization stage. The tree construction stage is associated with a DOM
Document object when a parser is created. The "output" of this stage consists of
dynamically modifying or extending that document's DOM tree.
This specification does not define when an interactive user agent has to render the
Document so that it is available to the user, or when it has to begin accepting user
input.
When the steps below require the user agent to insert an HTML element for a token, the user agent must insert a foreign element for the token, with the HTML namespace and false.
When the steps below require the user agent to adjust SVG attributes for a token, then, for each attribute on the token whose attribute name is one of the ones in the first column of the following table, change the attribute's name to the name given in the corresponding cell in the second column. (This fixes the case of SVG attributes that are not all lowercase.)
| Attribute name on token | Attribute name on element |
|---|---|
attributename | attributeName
|
attributetype | attributeType
|
basefrequency | baseFrequency
|
baseprofile | baseProfile
|
calcmode | calcMode
|
clippathunits | clipPathUnits
|
diffuseconstant | diffuseConstant
|
edgemode | edgeMode
|
filterunits | filterUnits
|
glyphref | glyphRef
|
gradienttransform | gradientTransform
|
gradientunits | gradientUnits
|
kernelmatrix | kernelMatrix
|
kernelunitlength | kernelUnitLength
|
keypoints | keyPoints
|
keysplines | keySplines
|
keytimes | keyTimes
|
lengthadjust | lengthAdjust
|
limitingconeangle | limitingConeAngle
|
markerheight | markerHeight
|
markerunits | markerUnits
|
markerwidth | markerWidth
|
maskcontentunits | maskContentUnits
|
maskunits | maskUnits
|
numoctaves | numOctaves
|
pathlength | pathLength
|
patterncontentunits | patternContentUnits
|
patterntransform | patternTransform
|
patternunits | patternUnits
|
pointsatx | pointsAtX
|
pointsaty | pointsAtY
|
pointsatz | pointsAtZ
|
preservealpha | preserveAlpha
|
preserveaspectratio | preserveAspectRatio
|
primitiveunits | primitiveUnits
|
refx | refX
|
refy | refY
|
repeatcount | repeatCount
|
repeatdur | repeatDur
|
requiredextensions | requiredExtensions
|
requiredfeatures | requiredFeatures
|
specularconstant | specularConstant
|
specularexponent | specularExponent
|
spreadmethod | spreadMethod
|
startoffset | startOffset
|
stddeviation | stdDeviation
|
stitchtiles | stitchTiles
|
surfacescale | surfaceScale
|
systemlanguage | systemLanguage
|
tablevalues | tableValues
|
targetx | targetX
|
targety | targetY
|
textlength | textLength
|
viewbox | viewBox
|
viewtarget | viewTarget
|
xchannelselector | xChannelSelector
|
ychannelselector | yChannelSelector
|
zoomandpan | zoomAndPan
|
When the steps below require the user agent to adjust foreign attributes for a
token, then, if any of the attributes on the token match the strings given in the first column of
the following table, let the attribute be a namespaced attribute, with the prefix being the string
given in the corresponding cell in the second column, the local name being the string given in the
corresponding cell in the third column, and the namespace being the namespace given in the
corresponding cell in the fourth column. (This fixes the use of namespaced attributes, in
particular lang attributes in the XML
namespace.)
| Attribute name | Prefix | Local name | Namespace |
|---|---|---|---|
xlink:actuate | xlink | actuate | XLink namespace |
xlink:arcrole | xlink | arcrole | XLink namespace |
xlink:href | xlink | href | XLink namespace |
xlink:role | xlink | role | XLink namespace |
xlink:show | xlink | show | XLink namespace |
xlink:title | xlink | title | XLink namespace |
xlink:type | xlink | type | XLink namespace |
xml:lang | xml | lang | XML namespace |
xml:space | xml | space | XML namespace |
xmlns | (none) | xmlns | XMLNS namespace |
xmlns:xlink | xmlns | xlink | XMLNS namespace |
The generic raw text element parsing algorithm and the generic RCDATA element parsing algorithm consist of the following steps. These algorithms are always invoked in response to a start tag token.
Insert an HTML element for the token.
If the algorithm that was invoked is the generic raw text element parsing algorithm, switch the tokenizer to the RAWTEXT state; otherwise the algorithm invoked was the generic RCDATA element parsing algorithm, switch the tokenizer to the RCDATA state.
Let the original insertion mode be the current insertion mode.
Then, switch the insertion mode to "text".
If a step requires the UA to generate implied end tags but lists an element to exclude from the process, then the UA must perform the above steps as if that element was not in the above list.
When the steps below require the UA to generate all implied end tags thoroughly,
then, while the current node is a caption element, a
colgroup element, a dd element, a dt element, an
li element, an optgroup element, an option element, a
p element, an rb element, an rp element, an rt
element, an rtc element, a tbody element, a td element, a
tfoot element, a th element, a thead element, or a
tr element, the UA must pop the current node off the
stack of open elements.
When the user agent is to apply the rules for the "initial" insertion mode, the user agent must handle the token as follows:
Ignore the token.
Insert a comment as the last child of the Document object.
If the DOCTYPE token's name is not "html", or the token's public
identifier is not missing, or the token's system identifier is neither missing nor
"about:legacy-compat", then there is a parse error.
Append a DocumentType node to the Document node, with its name set to the name given in the DOCTYPE token, or the
empty string if the name was missing; its public
ID set to the public identifier given in the DOCTYPE token, or the empty string if the
public identifier was missing; and its system ID
set to the system identifier given in the DOCTYPE token, or the empty string if the system
identifier was missing.
Then, if the document is not an iframe
srcdoc document, and the parser cannot
change the mode flag is false, and the DOCTYPE token matches one of the conditions in the
following list, then set the Document to quirks mode:
html". -//W3O//DTD W3 HTML Strict 3.0//EN//" -/W3C/DTD HTML 4.0 Transitional/EN" HTML" http://www.ibm.com/data/dtd/v11/ibmxhtml1-transitional.dtd" +//Silmaril//dtd html Pro v0r11 19970101//" -//AS//DTD HTML 3.0 asWedit + extensions//" -//AdvaSoft Ltd//DTD HTML 3.0 asWedit + extensions//" -//IETF//DTD HTML 2.0 Level 1//" -//IETF//DTD HTML 2.0 Level 2//" -//IETF//DTD HTML 2.0 Strict Level 1//" -//IETF//DTD HTML 2.0 Strict Level 2//" -//IETF//DTD HTML 2.0 Strict//" -//IETF//DTD HTML 2.0//" -//IETF//DTD HTML 2.1E//" -//IETF//DTD HTML 3.0//" -//IETF//DTD HTML 3.2 Final//" -//IETF//DTD HTML 3.2//" -//IETF//DTD HTML 3//" -//IETF//DTD HTML Level 0//" -//IETF//DTD HTML Level 1//" -//IETF//DTD HTML Level 2//" -//IETF//DTD HTML Level 3//" -//IETF//DTD HTML Strict Level 0//" -//IETF//DTD HTML Strict Level 1//" -//IETF//DTD HTML Strict Level 2//" -//IETF//DTD HTML Strict Level 3//" -//IETF//DTD HTML Strict//" -//IETF//DTD HTML//" -//Metrius//DTD Metrius Presentational//" -//Microsoft//DTD Internet Explorer 2.0 HTML Strict//" -//Microsoft//DTD Internet Explorer 2.0 HTML//" -//Microsoft//DTD Internet Explorer 2.0 Tables//" -//Microsoft//DTD Internet Explorer 3.0 HTML Strict//" -//Microsoft//DTD Internet Explorer 3.0 HTML//" -//Microsoft//DTD Internet Explorer 3.0 Tables//" -//Netscape Comm. Corp.//DTD HTML//" -//Netscape Comm. Corp.//DTD Strict HTML//" -//O'Reilly and Associates//DTD HTML 2.0//" -//O'Reilly and Associates//DTD HTML Extended 1.0//" -//O'Reilly and Associates//DTD HTML Extended Relaxed 1.0//" -//SQ//DTD HTML 2.0 HoTMetaL + extensions//" -//SoftQuad Software//DTD HoTMetaL PRO 6.0::19990601::extensions to HTML 4.0//" -//SoftQuad//DTD HoTMetaL PRO 4.0::19971010::extensions to HTML 4.0//" -//Spyglass//DTD HTML 2.0 Extended//" -//Sun Microsystems Corp.//DTD HotJava HTML//" -//Sun Microsystems Corp.//DTD HotJava Strict HTML//" -//W3C//DTD HTML 3 1995-03-24//" -//W3C//DTD HTML 3.2 Draft//" -//W3C//DTD HTML 3.2 Final//" -//W3C//DTD HTML 3.2//" -//W3C//DTD HTML 3.2S Draft//" -//W3C//DTD HTML 4.0 Frameset//" -//W3C//DTD HTML 4.0 Transitional//" -//W3C//DTD HTML Experimental 19960712//" -//W3C//DTD HTML Experimental 970421//" -//W3C//DTD W3 HTML//" -//W3O//DTD W3 HTML 3.0//" -//WebTechs//DTD Mozilla HTML 2.0//" -//WebTechs//DTD Mozilla HTML//" -//W3C//DTD HTML 4.01 Frameset//" -//W3C//DTD HTML 4.01 Transitional//" Otherwise, if the document is not an iframe srcdoc document, and the parser cannot change
the mode flag is false, and the DOCTYPE token matches one of the conditions in the
following list, then set the Document to limited-quirks mode:
-//W3C//DTD XHTML 1.0 Frameset//" -//W3C//DTD XHTML 1.0 Transitional//" -//W3C//DTD HTML 4.01 Frameset//" -//W3C//DTD HTML 4.01 Transitional//" The system identifier and public identifier strings must be compared to the values given in the lists above in an ASCII case-insensitive manner. A system identifier whose value is the empty string is not considered missing for the purposes of the conditions above.
Then, switch the insertion mode to "before html".
If the document is not an iframe srcdoc document, then this is a parse
error; if the parser cannot change the mode flag is false, set the
Document to quirks mode.
In any case, switch the insertion mode to "before html", then reprocess the token.
When the user agent is to apply the rules for the "before html" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Insert a comment as the last child of the Document object.
Ignore the token.
Create an element for the token in the HTML namespace, with the
Document as the intended parent. Append it to the Document object. Put
this element in the stack of open elements.
Switch the insertion mode to "before head".
Act as described in the "anything else" entry below.
Parse error. Ignore the token.
Create an html element whose node document is the Document object. Append
it to the Document object. Put this element in the stack of open
elements.
Switch the insertion mode to "before head", then reprocess the token.
The document element can end up being removed from the Document
object, e.g. by scripts; nothing in particular happens in such cases, content continues being
appended to the nodes as described in the next section.
When the user agent is to apply the rules for the "before head" insertion mode, the user agent must handle the token as follows:
Ignore the token.
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Insert an HTML element for the token.
Set the head element pointer to the newly created
head element.
Switch the insertion mode to "in head".
Act as described in the "anything else" entry below.
Parse error. Ignore the token.
Insert an HTML element for a "head" start tag token with no attributes.
Set the head element pointer to the newly created
head element.
Switch the insertion mode to "in head".
Reprocess the current token.
When the user agent is to apply the rules for the "in head" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
If the active speculative HTML parser is null, then:
If the element has a charset attribute, and getting an encoding from
its value results in an encoding, and the
confidence is currently tentative,
then change the encoding to the resulting encoding.
Otherwise, if the element has an http-equiv
attribute whose value is an ASCII case-insensitive match for the string "Content-Type", and the element has a content attribute, and applying the algorithm for
extracting a character encoding from a meta element to that attribute's
value returns an encoding, and the
confidence is currently tentative,
then change the encoding to the extracted encoding.
Follow the generic RCDATA element parsing algorithm.
Follow the generic raw text element parsing algorithm.
Insert an HTML element for the token.
Switch the insertion mode to "in head noscript".
Run these steps:
Let the adjusted insertion location be the appropriate place for inserting a node.
Create an element for the token in the HTML namespace, with the intended parent being the element in which the adjusted insertion location finds itself.
Set the element's parser document to the Document, and set the
element's force async to false.
If the parser was created as part of the HTML fragment parsing algorithm,
then set the script element's already started to true.
(fragment case)
If the parser was invoked via the document.write() or document.writeln() methods, then optionally set the
script element's already started to true. (For example, the user
agent might use this clause to prevent execution of cross-origin
scripts inserted via document.write() under slow
network conditions, or when the page has already taken a long time to load.)
Insert the newly created element at the adjusted insertion location.
Push the element onto the stack of open elements so that it is the new current node.
Switch the tokenizer to the script data state.
Let the original insertion mode be the current insertion mode.
Switch the insertion mode to "text".
Pop the current node (which will be the head element) off the
stack of open elements.
Switch the insertion mode to "after head".
Act as described in the "anything else" entry below.
Let template start tag be the start tag.
Insert a marker at the end of the list of active formatting elements.
Set the frameset-ok flag to "not ok".
Switch the insertion mode to "in template".
Push "in template" onto the stack of template insertion modes so that it is the new current template insertion mode.
Let the adjusted insertion location be the appropriate place for inserting a node.
Let intended parent be the element in which the adjusted insertion location finds itself.
Let document be intended parent's node document.
If any of the following are false:
shadowrootmode is not in
the none state;then insert an HTML element for the token.
Otherwise:
Let declarative shadow host element be adjusted current node.
Let template be the result of insert a foreign element for template start tag, with HTML namespace and true.
Let mode be template start tag's shadowrootmode attribute's value.
Let clonable be true if template start tag has a shadowrootclonable attribute; otherwise
false.
Let serializable be true if template start tag has a shadowrootserializable attribute;
otherwise false.
Let delegatesFocus be true if template start tag has a shadowrootdelegatesfocus attribute;
otherwise false.
If declarative shadow host element is a shadow host, then insert an element at the adjusted insertion location with template.
Otherwise:
Attach a shadow root with
declarative shadow host element, mode, clonable,
serializable, delegatesFocus, and "named".
If an exception is thrown, then catch it and:
Insert an element at the adjusted insertion location with template.
The user agent may report an error to the developer console.
Return.
Let shadow be declarative shadow host element's shadow root.
Set shadow's declarative to true.
Set template's template contents property to shadow.
Set shadow's available to element internals to true.
If there is no template element on the stack of open elements, then
this is a parse error; ignore the token.
Otherwise, run these steps:
If the current node is not a template element, then this is a
parse error.
Pop elements from the stack of open elements until a template
element has been popped from the stack.
Pop the current template insertion mode off the stack of template insertion modes.
Parse error. Ignore the token.
Pop the current node (which will be the head element) off the
stack of open elements.
Switch the insertion mode to "after head".
Reprocess the token.
When the user agent is to apply the rules for the "in head noscript" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Pop the current node (which will be a noscript element) from the
stack of open elements; the new current node will be a
head element.
Switch the insertion mode to "in head".
Process the token using the rules for the "in head" insertion mode.
Act as described in the "anything else" entry below.
Parse error. Ignore the token.
Pop the current node (which will be a noscript element) from the
stack of open elements; the new current node will be a
head element.
Switch the insertion mode to "in head".
Reprocess the token.
When the user agent is to apply the rules for the "after head" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Insert an HTML element for the token.
Set the frameset-ok flag to "not ok".
Switch the insertion mode to "in body".
Insert an HTML element for the token.
Switch the insertion mode to "in frameset".
Push the node pointed to by the head element pointer onto
the stack of open elements.
Process the token using the rules for the "in head" insertion mode.
Remove the node pointed to by the head element pointer
from the stack of open elements. (It might not be the current node at
this point.)
Process the token using the rules for the "in head" insertion mode.
Act as described in the "anything else" entry below.
Parse error. Ignore the token.
Insert an HTML element for a "body" start tag token with no attributes.
Switch the insertion mode to "in body".
Reprocess the current token.
When the user agent is to apply the rules for the "in body" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Reconstruct the active formatting elements, if any.
Set the frameset-ok flag to "not ok".
Parse error. Ignore the token.
If there is a template element on the stack of open elements, then
ignore the token.
Otherwise, for each attribute on the token, check to see if the attribute is already present on the top element of the stack of open elements. If it is not, add the attribute and its corresponding value to that element.
Process the token using the rules for the "in head" insertion mode.
If the stack of open elements has only one node on it, if the second element
on the stack of open elements is not a body element, or if there is a
template element on the stack of open elements, then ignore the token.
(fragment case or there is a template element on the stack)
Otherwise, set the frameset-ok flag to "not ok"; then, for each attribute on the
token, check to see if the attribute is already present on the body element (the
second element) on the stack of open elements, and if it is not, add the attribute
and its corresponding value to that element.
If the stack of open elements has only one node on it, or if the second element
on the stack of open elements is not a body element, then ignore the
token. (fragment case or there is a template element on the
stack)
If the frameset-ok flag is set to "not ok", ignore the token.
Otherwise, run the following steps:
Remove the second element on the stack of open elements from its parent node, if it has one.
Pop all the nodes from the bottom of the stack of open elements, from the
current node up to, but not including, the root html element.
Insert an HTML element for the token.
Switch the insertion mode to "in frameset".
If the stack of template insertion modes is not empty, then process the token using the rules for the "in template" insertion mode.
Otherwise, follow these steps:
If there is a node in the stack of open elements that is not either a
dd element, a dt element, an li element, an
optgroup element, an option element, a p element, an
rb element, an rp element, an rt element, an
rtc element, a tbody element, a td element, a
tfoot element, a th element, a thead element, a
tr element, the body element, or the html element, then
this is a parse error.
If the stack of open elements does not have a body element in scope, this is a parse error;
ignore the token.
Otherwise, if there is a node in the stack of open elements that is not either a
dd element, a dt element, an li element, an
optgroup element, an option element, a p element, an
rb element, an rp element, an rt element, an
rtc element, a tbody element, a td element, a
tfoot element, a th element, a thead element, a
tr element, the body element, or the html element, then
this is a parse error.
Switch the insertion mode to "after body".
If the stack of open elements does not have a body element in scope, this is a parse error;
ignore the token.
Otherwise, if there is a node in the stack of open elements that is not either a
dd element, a dt element, an li element, an
optgroup element, an option element, a p element, an
rb element, an rp element, an rt element, an
rtc element, a tbody element, a td element, a
tfoot element, a th element, a thead element, a
tr element, the body element, or the html element, then
this is a parse error.
Switch the insertion mode to "after body".
Reprocess the token.
If the stack of open elements has a
p element in button scope, then close a p
element.
Insert an HTML element for the token.
If the stack of open elements has a
p element in button scope, then close a p
element.
If the current node is an HTML element whose tag name is one of "h1", "h2", "h3", "h4", "h5", or "h6", then this is a parse error; pop the current node off the stack of open elements.
Insert an HTML element for the token.
If the stack of open elements has
a p element in button scope, then close a p
element.
Insert an HTML element for the token.
If the next token is a U+000A LINE FEED (LF) character token, then ignore that
token and move on to the next one. (Newlines at the start of pre blocks are ignored
as an authoring convenience.)
Set the frameset-ok flag to "not ok".
If the form element pointer is not null, and there is
no template element on the stack of open elements, then this is a
parse error; ignore the token.
Otherwise:
If the stack of open elements has
a p element in button scope, then close a p
element.
Insert an HTML element for the token, and, if there is no template
element on the stack of open elements, set the form element pointer to point to the element created.
Run these steps:
Set the frameset-ok flag to "not ok".
Initialize node to be the current node (the bottommost node of the stack).
Loop: If node is an li element, then run these
substeps:
Generate implied end tags, except for li elements.
If the current node is not an li element, then this is a
parse error.
Pop elements from the stack of open elements until an li
element has been popped from the stack.
Jump to the step labeled done below.
If node is in the special category, but is not an
address, div, or p element, then jump to the step
labeled done below.
Otherwise, set node to the previous entry in the stack of open elements and return to the step labeled loop.
Done: If the stack of open elements has a p element in button scope, then close a
p element.
Finally, insert an HTML element for the token.
Run these steps:
Set the frameset-ok flag to "not ok".
Initialize node to be the current node (the bottommost node of the stack).
Loop: If node is a dd element, then run these
substeps:
Generate implied end tags, except for dd elements.
If the current node is not a dd element, then this is a
parse error.
Pop elements from the stack of open elements until a dd
element has been popped from the stack.
Jump to the step labeled done below.
If node is a dt element, then run these substeps:
Generate implied end tags, except for dt elements.
If the current node is not a dt element, then this is a
parse error.
Pop elements from the stack of open elements until a dt
element has been popped from the stack.
Jump to the step labeled done below.
If node is in the special category, but is not an
address, div, or p element, then jump to the step
labeled done below.
Otherwise, set node to the previous entry in the stack of open elements and return to the step labeled loop.
Done: If the stack of open elements has a p element in button scope, then close a
p element.
Finally, insert an HTML element for the token.
If the stack of open elements has a
p element in button scope, then close a p
element.
Insert an HTML element for the token.
Switch the tokenizer to the PLAINTEXT state.
If the stack of open elements has a
button element in scope, then run these substeps:
Pop elements from the stack of open elements until a button
element has been popped from the stack.
Insert an HTML element for the token.
Set the frameset-ok flag to "not ok".
If the stack of open elements does not have an element in scope that is an HTML element with the same tag name as that of the token, then this is a parse error; ignore the token.
Otherwise, run these steps:
If the current node is not an HTML element with the same tag name as that of the token, then this is a parse error.
Pop elements from the stack of open elements until an HTML element with the same tag name as the token has been popped from the stack.
If there is no template element on the stack of open elements, then
run these substeps:
Let node be the element that the form
element pointer is set to, or null if it is not set to an element.
Set the form element pointer to null.
If node is null or if the stack of open elements does not have node in scope, then this is a parse error; return and ignore the token.
If the current node is not node, then this is a parse error.
Remove node from the stack of open elements.
If there is a template element on the stack of open
elements, then run these substeps instead:
If the stack of open elements does not have a form element in scope, then this is a parse
error; return and ignore the token.
If the current node is not a form element, then this is a
parse error.
Pop elements from the stack of open elements until a form
element has been popped from the stack.
If the stack of open elements does not have a p element in button scope, then this is a parse
error; insert an HTML element for a "p" start tag token with no
attributes.
If the stack of open elements does not have an li element in list item scope, then this is a parse
error; ignore the token.
Otherwise, run these steps:
Generate implied end tags, except for li elements.
If the current node is not an li element, then this is a
parse error.
Pop elements from the stack of open elements until an li
element has been popped from the stack.
If the stack of open elements does not have an element in scope that is an HTML element with the same tag name as that of the token, then this is a parse error; ignore the token.
Otherwise, run these steps:
Generate implied end tags, except for HTML elements with the same tag name as the token.
If the current node is not an HTML element with the same tag name as that of the token, then this is a parse error.
Pop elements from the stack of open elements until an HTML element with the same tag name as the token has been popped from the stack.
If the stack of open elements does not have an element in scope that is an HTML element and whose tag name is one of "h1", "h2", "h3", "h4", "h5", or "h6", then this is a parse error; ignore the token.
Otherwise, run these steps:
If the current node is not an HTML element with the same tag name as that of the token, then this is a parse error.
Pop elements from the stack of open elements until an HTML element whose tag name is one of "h1", "h2", "h3", "h4", "h5", or "h6" has been popped from the stack.
Take a deep breath, then act as described in the "any other end tag" entry below.
If the list of active formatting elements contains an a element
between the end of the list and the last marker on
the list (or the start of the list if there is no marker on the list), then this is a parse
error; run the adoption agency algorithm for the token, then remove that
element from the list of active formatting elements and the stack of open
elements if the adoption agency algorithm didn't already remove it (it might
not have if the element is not in table
scope).
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token. Push onto the list of active formatting elements that element.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token. Push onto the list of active formatting elements that element.
Reconstruct the active formatting elements, if any.
If the stack of open elements has a
nobr element in scope, then this is a parse error; run the
adoption agency algorithm for the token, then once again reconstruct the
active formatting elements, if any.
Insert an HTML element for the token. Push onto the list of active formatting elements that element.
Run the adoption agency algorithm for the token.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token.
Insert a marker at the end of the list of active formatting elements.
Set the frameset-ok flag to "not ok".
If the stack of open elements does not have an element in scope that is an HTML element with the same tag name as that of the token, then this is a parse error; ignore the token.
Otherwise, run these steps:
If the current node is not an HTML element with the same tag name as that of the token, then this is a parse error.
Pop elements from the stack of open elements until an HTML element with the same tag name as the token has been popped from the stack.
If the Document is not set to quirks mode, and the
stack of open elements has a
p element in button scope, then close a p
element.
Insert an HTML element for the token.
Set the frameset-ok flag to "not ok".
Switch the insertion mode to "in table".
Parse error. Drop the attributes from the token, and act as described in the next entry; i.e. act as if this was a "br" start tag token with no attributes, rather than the end tag token that it actually is.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
Set the frameset-ok flag to "not ok".
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
If the token does not have an attribute with the name "type", or if it does, but that
attribute's value is not an ASCII case-insensitive match for the string "hidden", then: set the frameset-ok flag to "not ok".
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
If the stack of open elements has a
p element in button scope, then close a p
element.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
Set the frameset-ok flag to "not ok".
Parse error. Change the token's tag name to "img" and reprocess it. (Don't ask.)
Run these steps:
Insert an HTML element for the token.
If the next token is a U+000A LINE FEED (LF) character token, then ignore
that token and move on to the next one. (Newlines at the start of textarea
elements are ignored as an authoring convenience.)
Switch the tokenizer to the RCDATA state.
Let the original insertion mode be the current insertion mode.
Set the frameset-ok flag to "not ok".
Switch the insertion mode to "text".
If the stack of open elements has a
p element in button scope, then close a p
element.
Reconstruct the active formatting elements, if any.
Set the frameset-ok flag to "not ok".
Follow the generic raw text element parsing algorithm.
Set the frameset-ok flag to "not ok".
Follow the generic raw text element parsing algorithm.
Follow the generic raw text element parsing algorithm.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token.
Set the frameset-ok flag to "not ok".
If the insertion mode is one of "in table", "in caption", "in table body", "in row", or "in cell", then switch the insertion mode to "in select in table". Otherwise, switch the insertion mode to "in select".
If the current node is an option element, then pop the
current node off the stack of open elements.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token.
If the stack of open elements has a
ruby element in scope, then generate implied end tags. If the
current node is not now a ruby element, this is a
parse error.
Insert an HTML element for the token.
If the stack of open elements has a
ruby element in scope, then generate implied end tags, except
for rtc elements. If the current node is not now a rtc
element or a ruby element, this is a parse error.
Insert an HTML element for the token.
Reconstruct the active formatting elements, if any.
Adjust MathML attributes for the token. (This fixes the case of MathML attributes that are not all lowercase.)
Adjust foreign attributes for the token. (This fixes the use of namespaced attributes, in particular XLink.)
Insert a foreign element for the token, with MathML namespace and false.
If the token has its self-closing flag set, pop the current node off the stack of open elements and acknowledge the token's self-closing flag.
Reconstruct the active formatting elements, if any.
Adjust SVG attributes for the token. (This fixes the case of SVG attributes that are not all lowercase.)
Adjust foreign attributes for the token. (This fixes the use of namespaced attributes, in particular XLink in SVG.)
Insert a foreign element for the token, with SVG namespace and false.
If the token has its self-closing flag set, pop the current node off the stack of open elements and acknowledge the token's self-closing flag.
Parse error. Ignore the token.
Reconstruct the active formatting elements, if any.
Insert an HTML element for the token.
Run these steps:
Initialize node to be the current node (the bottommost node of the stack).
Loop: If node is an HTML element with the same tag name as the token, then:
Generate implied end tags, except for HTML elements with the same tag name as the token.
If node is not the current node, then this is a parse error.
Pop all the nodes from the current node up to node, including node, then stop these steps.
Otherwise, if node is in the special category, then this is a parse error; ignore the token, and return.
Set node to the previous entry in the stack of open elements.
Return to the step labeled loop.
When the user agent is to apply the rules for the "text" insertion mode, the user agent must handle the token as follows:
If the current node is a script element, then set its already
started to true.
Pop the current node off the stack of open elements.
Switch the insertion mode to the original insertion mode and reprocess the token.
If the active speculative HTML parser is null and the JavaScript execution context stack is empty, then perform a microtask checkpoint.
Let script be the current node (which will be a
script element).
Pop the current node off the stack of open elements.
Switch the insertion mode to the original insertion mode.
Let the old insertion point have the same value as the current insertion point. Let the insertion point be just before the next input character.
Increment the parser's script nesting level by one.
If the active speculative HTML parser is null, then prepare the script element script. This might cause some script to execute, which might cause new characters to be inserted into the tokenizer, and might cause the tokenizer to output more tokens, resulting in a reentrant invocation of the parser.
Decrement the parser's script nesting level by one. If the parser's script nesting level is zero, then set the parser pause flag to false.
Let the insertion point have the value of the old insertion point. (In other words, restore the insertion point to its previous value. This value might be the "undefined" value.)
At this stage, if the pending parsing-blocking script is not null, then:
Set the parser pause flag to true, and abort the processing of any nested invocations of the tokenizer, yielding control back to the caller. (Tokenization will resume when the caller returns to the "outer" tree construction stage.)
While the pending parsing-blocking script is not null:
Let the script be the pending parsing-blocking script.
Set the pending parsing-blocking script to null.
Start the speculative HTML parser for this instance of the HTML parser.
Block the tokenizer for this instance of the HTML parser, such that the event loop will not run tasks that invoke the tokenizer.
If the parser's Document has a style sheet that is blocking
scripts or the script's ready to be parser-executed is false:
spin the event loop until the parser's Document has no style
sheet that is blocking scripts and the script's ready to be
parser-executed becomes true.
If this parser has been aborted in the meantime, return.
Stop the speculative HTML parser for this instance of the HTML parser.
Unblock the tokenizer for this instance of the HTML parser, such that tasks that invoke the tokenizer can again be run.
Let the insertion point be just before the next input character.
Increment the parser's script nesting level by one (it should be zero before this step, so this sets it to one).
Execute the script element the script.
Decrement the parser's script nesting level by one. If the parser's script nesting level is zero (which it always should be at this point), then set the parser pause flag to false.
Let the insertion point be undefined again.
Pop the current node off the stack of open elements.
Switch the insertion mode to the original insertion mode.
When the user agent is to apply the rules for the "in table" insertion mode, the user agent must handle the token as follows:
table, tbody, template, tfoot, thead, or tr elementLet the original insertion mode be the current insertion mode.
Switch the insertion mode to "in table text" and reprocess the token.
Parse error. Ignore the token.
Clear the stack back to a table context. (See below.)
Insert a marker at the end of the list of active formatting elements.
Insert an HTML element for the token, then switch the insertion mode to "in caption".
Clear the stack back to a table context. (See below.)
Insert an HTML element for the token, then switch the insertion mode to "in column group".
Clear the stack back to a table context. (See below.)
Insert an HTML element for a "colgroup" start tag token with no attributes, then switch the insertion mode to "in column group".
Reprocess the current token.
Clear the stack back to a table context. (See below.)
Insert an HTML element for the token, then switch the insertion mode to "in table body".
Clear the stack back to a table context. (See below.)
Insert an HTML element for a "tbody" start tag token with no attributes, then switch the insertion mode to "in table body".
Reprocess the current token.
If the stack of open elements does not have a table element in table scope, ignore the token.
Otherwise:
Pop elements from this stack until a table element has been popped from the
stack.
Reset the insertion mode appropriately.
Reprocess the token.
If the stack of open elements does not have a table element in table scope, this is a parse
error; ignore the token.
Otherwise:
Pop elements from this stack until a table element has been popped from the
stack.
Parse error. Ignore the token.
Process the token using the rules for the "in head" insertion mode.
If the token does not have an attribute with the name "type", or if it does, but that
attribute's value is not an ASCII case-insensitive match for the string "hidden", then: act as described in the "anything else" entry below.
Otherwise:
Insert an HTML element for the token.
Pop that input element off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
If there is a template element on the stack of open elements, or if
the form element pointer is not null, ignore the
token.
Otherwise:
Insert an HTML element for the token, and set the form element pointer to point to the element created.
Pop that form element off the stack of open elements.
Process the token using the rules for the "in body" insertion mode.
Parse error. Enable foster parenting, process the token using the rules for the "in body" insertion mode, and then disable foster parenting.
When the steps above require the UA to clear the stack back to a table context, it
means that the UA must, while the current node is not a table,
template, or html element, pop elements from the stack of open
elements.
When the user agent is to apply the rules for the "in table text" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Append the character token to the pending table character tokens list.
If any of the tokens in the pending table character tokens list are character tokens that are not ASCII whitespace, then this is a parse error: reprocess the character tokens in the pending table character tokens list using the rules given in the "anything else" entry in the "in table" insertion mode.
Otherwise, insert the characters given by the pending table character tokens list.
Switch the insertion mode to the original insertion mode and reprocess the token.
When the user agent is to apply the rules for the "in caption" insertion mode, the user agent must handle the token as follows:
If the stack of open elements does not have a caption element in table scope, this is a parse
error; ignore the token. (fragment case)
Otherwise:
Now, if the current node is not a caption element, then this is a
parse error.
Pop elements from this stack until a caption element has been popped from the
stack.
Clear the list of active formatting elements up to the last marker.
Switch the insertion mode to "in table".
If the stack of open elements does not have a caption element in table scope, this is a parse
error; ignore the token. (fragment case)
Otherwise:
Now, if the current node is not a caption element, then this is a
parse error.
Pop elements from this stack until a caption element has been popped from the
stack.
Clear the list of active formatting elements up to the last marker.
Switch the insertion mode to "in table".
Reprocess the token.
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
When the user agent is to apply the rules for the "in column group" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
If the current node is not a colgroup element, then this is a
parse error; ignore the token.
Otherwise, pop the current node from the stack of open elements. Switch the insertion mode to "in table".
Parse error. Ignore the token.
Process the token using the rules for the "in head" insertion mode.
Process the token using the rules for the "in body" insertion mode.
If the current node is not a colgroup element, then this is a
parse error; ignore the token.
Otherwise, pop the current node from the stack of open elements.
Switch the insertion mode to "in table".
Reprocess the token.
When the user agent is to apply the rules for the "in table body" insertion mode, the user agent must handle the token as follows:
Clear the stack back to a table body context. (See below.)
Insert an HTML element for the token, then switch the insertion mode to "in row".
Clear the stack back to a table body context. (See below.)
Insert an HTML element for a "tr" start tag token with no attributes, then switch the insertion mode to "in row".
Reprocess the current token.
If the stack of open elements does not have an element in table scope that is an HTML element with the same tag name as the token, this is a parse error; ignore the token.
Otherwise:
Clear the stack back to a table body context. (See below.)
Pop the current node from the stack of open elements. Switch the insertion mode to "in table".
If the stack of open elements does not have a tbody, thead, or tfoot element in table
scope, this is a parse error; ignore the token.
Otherwise:
Clear the stack back to a table body context. (See below.)
Pop the current node from the stack of open elements. Switch the insertion mode to "in table".
Reprocess the token.
Parse error. Ignore the token.
Process the token using the rules for the "in table" insertion mode.
When the steps above require the UA to clear the stack back to a table body context,
it means that the UA must, while the current node is not a tbody,
tfoot, thead, template, or html element, pop
elements from the stack of open elements.
When the user agent is to apply the rules for the "in row" insertion mode, the user agent must handle the token as follows:
Clear the stack back to a table row context. (See below.)
Insert an HTML element for the token, then switch the insertion mode to "in cell".
Insert a marker at the end of the list of active formatting elements.
If the stack of open elements does not have a tr element in table scope, this is a parse error;
ignore the token.
Otherwise:
Clear the stack back to a table row context. (See below.)
Pop the current node (which will be a tr element) from the
stack of open elements. Switch the insertion mode to "in table body".
If the stack of open elements does not have a tr element in table scope, this is a parse error;
ignore the token.
Otherwise:
Clear the stack back to a table row context. (See below.)
Pop the current node (which will be a tr element) from the
stack of open elements. Switch the insertion mode to "in table body".
Reprocess the token.
If the stack of open elements does not have an element in table scope that is an HTML element with the same tag name as the token, this is a parse error; ignore the token.
If the stack of open elements does not have a tr element in table scope, ignore the token.
Otherwise:
Clear the stack back to a table row context. (See below.)
Pop the current node (which will be a tr element) from the
stack of open elements. Switch the insertion mode to "in table body".
Reprocess the token.
Parse error. Ignore the token.
Process the token using the rules for the "in table" insertion mode.
When the steps above require the UA to clear the stack back to a table row context,
it means that the UA must, while the current node is not a tr,
template, or html element, pop elements from the stack of open
elements.
When the user agent is to apply the rules for the "in cell" insertion mode, the user agent must handle the token as follows:
If the stack of open elements does not have an element in table scope that is an HTML element with the same tag name as that of the token, then this is a parse error; ignore the token.
Otherwise:
Now, if the current node is not an HTML element with the same tag name as the token, then this is a parse error.
Pop elements from the stack of open elements until an HTML element with the same tag name as the token has been popped from the stack.
Clear the list of active formatting elements up to the last marker.
Switch the insertion mode to "in row".
Assert: The stack of open elements has a td or th element in table scope.
Close the cell (see below) and reprocess the token.
Parse error. Ignore the token.
If the stack of open elements does not have an element in table scope that is an HTML element with the same tag name as that of the token, then this is a parse error; ignore the token.
Otherwise, close the cell (see below) and reprocess the token.
Process the token using the rules for the "in body" insertion mode.
When the user agent is to apply the rules for the "in select" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
If the current node is an option element, pop that node from the
stack of open elements.
Insert an HTML element for the token.
If the current node is an option element, pop that node from the
stack of open elements.
If the current node is an optgroup element, pop that node from the
stack of open elements.
Insert an HTML element for the token.
If the current node is an option element, pop that node from the
stack of open elements.
If the current node is an optgroup element, pop that node from the
stack of open elements.
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
First, if the current node is an option element, and the node
immediately before it in the stack of open elements is an optgroup
element, then pop the current node from the stack of open
elements.
If the current node is an optgroup element, then pop that node from
the stack of open elements. Otherwise, this is a parse error; ignore
the token.
If the current node is an option element, then pop that node from
the stack of open elements. Otherwise, this is a parse error; ignore
the token.
If the stack of open elements does not have a select element in select scope, this is a parse
error; ignore the token. (fragment case)
Otherwise:
Pop elements from the stack of open elements until a select element
has been popped from the stack.
If the stack of open elements does not have a select element in select scope, ignore the token.
(fragment case)
Otherwise:
Pop elements from the stack of open elements until a select element
has been popped from the stack.
If the stack of open elements does not have a select element in select scope, ignore the token.
(fragment case)
Otherwise:
Pop elements from the stack of open elements until a select element
has been popped from the stack.
Reset the insertion mode appropriately.
Reprocess the token.
Process the token using the rules for the "in head" insertion mode.
Process the token using the rules for the "in body" insertion mode.
Parse error. Ignore the token.
When the user agent is to apply the rules for the "in select in table" insertion mode, the user agent must handle the token as follows:
Pop elements from the stack of open elements until a select element
has been popped from the stack.
Reset the insertion mode appropriately.
Reprocess the token.
If the stack of open elements does not have an element in table scope that is an HTML element with the same tag name as that of the token, then ignore the token.
Otherwise:
Pop elements from the stack of open elements until a select element
has been popped from the stack.
Reset the insertion mode appropriately.
Reprocess the token.
Process the token using the rules for the "in select" insertion mode.
When the user agent is to apply the rules for the "in template" insertion mode, the user agent must handle the token as follows:
Process the token using the rules for the "in body" insertion mode.
Process the token using the rules for the "in head" insertion mode.
Pop the current template insertion mode off the stack of template insertion modes.
Push "in table" onto the stack of template insertion modes so that it is the new current template insertion mode.
Switch the insertion mode to "in table", and reprocess the token.
Pop the current template insertion mode off the stack of template insertion modes.
Push "in column group" onto the stack of template insertion modes so that it is the new current template insertion mode.
Switch the insertion mode to "in column group", and reprocess the token.
Pop the current template insertion mode off the stack of template insertion modes.
Push "in table body" onto the stack of template insertion modes so that it is the new current template insertion mode.
Switch the insertion mode to "in table body", and reprocess the token.
Pop the current template insertion mode off the stack of template insertion modes.
Push "in row" onto the stack of template insertion modes so that it is the new current template insertion mode.
Switch the insertion mode to "in row", and reprocess the token.
Pop the current template insertion mode off the stack of template insertion modes.
Push "in body" onto the stack of template insertion modes so that it is the new current template insertion mode.
Switch the insertion mode to "in body", and reprocess the token.
Parse error. Ignore the token.
If there is no template element on the stack of open elements, then
stop parsing. (fragment case)
Otherwise, this is a parse error.
Pop elements from the stack of open elements until a template
element has been popped from the stack.
Clear the list of active formatting elements up to the last marker.
Pop the current template insertion mode off the stack of template insertion modes.
Reset the insertion mode appropriately.
Reprocess the token.
When the user agent is to apply the rules for the "after body" insertion mode, the user agent must handle the token as follows:
Process the token using the rules for the "in body" insertion mode.
Insert a comment as the last child of the first element in the stack of
open elements (the html element).
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
If the parser was created as part of the HTML fragment parsing algorithm, this is a parse error; ignore the token. (fragment case)
Otherwise, switch the insertion mode to "after after body".
Parse error. Switch the insertion mode to "in body" and reprocess the token.
When the user agent is to apply the rules for the "in frameset" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Insert an HTML element for the token.
If the current node is the root html element, then this is a
parse error; ignore the token. (fragment case)
Otherwise, pop the current node from the stack of open elements.
If the parser was not created as part of the HTML fragment parsing algorithm
(fragment case), and the current node is no longer a
frameset element, then switch the insertion mode to "after frameset".
Insert an HTML element for the token. Immediately pop the current node off the stack of open elements.
Acknowledge the token's self-closing flag, if it is set.
Process the token using the rules for the "in head" insertion mode.
If the current node is not the root html element, then this is a
parse error.
Parse error. Ignore the token.
When the user agent is to apply the rules for the "after frameset" insertion mode, the user agent must handle the token as follows:
Parse error. Ignore the token.
Process the token using the rules for the "in body" insertion mode.
Switch the insertion mode to "after after frameset".
Process the token using the rules for the "in head" insertion mode.
Parse error. Ignore the token.
When the user agent is to apply the rules for the "after after body" insertion mode, the user agent must handle the token as follows:
Insert a comment as the last child of the Document object.
Process the token using the rules for the "in body" insertion mode.
Parse error. Switch the insertion mode to "in body" and reprocess the token.
When the user agent is to apply the rules for the "after after frameset" insertion mode, the user agent must handle the token as follows:
Insert a comment as the last child of the Document object.
Process the token using the rules for the "in body" insertion mode.
Process the token using the rules for the "in head" insertion mode.
Parse error. Ignore the token.
When the user agent is to apply the rules for parsing tokens in foreign content, the user agent must handle the token as follows:
Parse error. Insert a U+FFFD REPLACEMENT CHARACTER character.
Set the frameset-ok flag to "not ok".
Parse error. Ignore the token.
While the current node is not a MathML text integration point, an HTML integration point, or an element in the HTML namespace, pop elements from the stack of open elements.
Reprocess the token according to the rules given in the section corresponding to the current insertion mode in HTML content.
If the adjusted current node is an element in the MathML namespace, adjust MathML attributes for the token. (This fixes the case of MathML attributes that are not all lowercase.)
If the adjusted current node is an element in the SVG namespace, and the token's tag name is one of the ones in the first column of the following table, change the tag name to the name given in the corresponding cell in the second column. (This fixes the case of SVG elements that are not all lowercase.)
| Tag name | Element name |
|---|---|
altglyph | altGlyph
|
altglyphdef | altGlyphDef
|
altglyphitem | altGlyphItem
|
animatecolor | animateColor
|
animatemotion | animateMotion
|
animatetransform | animateTransform
|
clippath | clipPath
|
feblend | feBlend
|
fecolormatrix | feColorMatrix
|
fecomponenttransfer | feComponentTransfer
|
fecomposite | feComposite
|
feconvolvematrix | feConvolveMatrix
|
fediffuselighting | feDiffuseLighting
|
fedisplacementmap | feDisplacementMap
|
fedistantlight | feDistantLight
|
fedropshadow | feDropShadow
|
feflood | feFlood
|
fefunca | feFuncA
|
fefuncb | feFuncB
|
fefuncg | feFuncG
|
fefuncr | feFuncR
|
fegaussianblur | feGaussianBlur
|
feimage | feImage
|
femerge | feMerge
|
femergenode | feMergeNode
|
femorphology | feMorphology
|
feoffset | feOffset
|
fepointlight | fePointLight
|
fespecularlighting | feSpecularLighting
|
fespotlight | feSpotLight
|
fetile | feTile
|
feturbulence | feTurbulence
|
foreignobject | foreignObject
|
glyphref | glyphRef
|
lineargradient | linearGradient
|
radialgradient | radialGradient
|
textpath | textPath
|
If the adjusted current node is an element in the SVG namespace, adjust SVG attributes for the token. (This fixes the case of SVG attributes that are not all lowercase.)
Adjust foreign attributes for the token. (This fixes the use of namespaced attributes, in particular XLink in SVG.)
Insert a foreign element for the token, with adjusted current node's namespace and false.
If the token has its self-closing flag set, then run the appropriate steps from the following list:
Acknowledge the token's self-closing flag, and then act as described in the steps for a "script" end tag below.
Pop the current node off the stack of open elements and acknowledge the token's self-closing flag.
script elementPop the current node off the stack of open elements.
Let the old insertion point have the same value as the current insertion point. Let the insertion point be just before the next input character.
Increment the parser's script nesting level by one. Set the parser pause flag to true.
If the active speculative HTML parser is null and the user agent supports SVG,
then Process the
SVG script element according to the SVG rules. [SVG]
Decrement the parser's script nesting level by one. If the parser's script nesting level is zero, then set the parser pause flag to false.
Let the insertion point have the value of the old insertion point. (In other words, restore the insertion point to its previous value. This value might be the "undefined" value.)
Run these steps:
Initialize node to be the current node (the bottommost node of the stack).
If node's tag name, converted to ASCII lowercase, is not the same as the tag name of the token, then this is a parse error.
Loop: If node is the topmost element in the stack of open elements, then return. (fragment case)
If node's tag name, converted to ASCII lowercase, is the same as the tag name of the token, pop elements from the stack of open elements until node has been popped from the stack, and then return.
Set node to the previous entry in the stack of open elements.
If node is not an element in the HTML namespace, return to the step labeled loop.
Otherwise, process the token according to the rules given in the section corresponding to the current insertion mode in HTML content.
Document/DOMContentLoaded_event
Support in all current engines.
Once the user agent stops parsing the document, the user agent must run the following steps:
Support in all current engines.
If the active speculative HTML parser is not null, then stop the speculative HTML parser and return.
Set the insertion point to undefined.
Update the current document readiness to "interactive".
Pop all the nodes off the stack of open elements.
While the list of scripts that will execute when the document has finished parsing is not empty:
Spin the event loop until the first script in the list
of scripts that will execute when the document has finished parsing has its ready
to be parser-executed set to true and the parser's Document
has no style sheet that is blocking scripts.
Execute the script element given by the first script in
the list of scripts that will execute when the document has finished
parsing.
Remove the first script element from the list of scripts that will
execute when the document has finished parsing (i.e. shift out the first entry in the
list).
Queue a global task on the DOM manipulation task source given the
Document's relevant global object to run the following substeps:
Set the Document's load timing info's DOM content loaded
event start time to the current high resolution time given the
Document's relevant global object.
Fire an event named DOMContentLoaded at the Document
object, with its bubbles attribute initialized to
true.
Set the Document's load timing info's DOM content loaded
event end time to the current high resolution time given the
Document's relevant global object.
Enable the client message queue of the
ServiceWorkerContainer object whose associated service worker client is the
Document object's relevant settings object.
Invoke WebDriver BiDi DOM content loaded with the Document's
browsing context, and a new WebDriver BiDi
navigation status whose id is the
Document object's during-loading
navigation ID for WebDriver BiDi, status
is "pending", and url is the Document object's URL.
Spin the event loop until the set of scripts that will execute as soon as possible and the list of scripts that will execute in order as soon as possible are empty.
Queue a global task on the DOM manipulation task source given the
Document's relevant global object to run the following steps:
Update the current document readiness to "complete".
If the Document object's browsing
context is null, then abort these steps.
Let window be the Document's relevant global
object.
Set the Document's load timing info's load event start
time to the current high resolution time given window.
Fire an event named load at window, with legacy target override
flag set.
Invoke WebDriver BiDi load complete with the Document's browsing context, and a new WebDriver BiDi
navigation status whose id is the
Document object's during-loading
navigation ID for WebDriver BiDi, status
is "complete", and url is the Document object's URL.
Set the Document object's during-loading navigation ID for WebDriver BiDi
to null.
Set the Document's load timing info's load event end
time to the current high resolution time given window.
Assert: Document's page showing is
false.
Set the Document's page showing flag to true.
Fire a page transition event named pageshow at window with false.
If the Document's print when loaded flag is set, then run the
printing steps.
User agents may implement an optimization, as described in this section, to speculatively fetch resources that are declared in the HTML markup while the HTML parser is waiting for a pending parsing-blocking script to be fetched and executed, or during normal parsing, at the time an element is created for a token. While this optimization is not defined in precise detail, there are some rules to consider for interoperability.
The speculative HTML parser will create speculative mock elements instead of normal elements. DOM operations that the tree builder normally does on elements are expected to work appropriately on speculative mock elements.
When the tree builder says to insert an element into a template element's
template contents, if that is a speculative mock element, and the
template element's template contents is not a
ShadowRoot node, instead do nothing. URLs found speculatively inside
non-declarative-shadow-root template elements might themselves be templates, and must
not be speculatively fetched.
When an application uses an HTML parser in conjunction with an XML pipeline, it is
possible that the constructed DOM is not compatible with the XML tool chain in certain subtle
ways. For example, an XML toolchain might not be able to represent attributes with the name xmlns, since they conflict with the Namespaces in XML syntax. There is also some
data that the HTML parser generates that isn't included in the DOM itself. This
section specifies some rules for handling these issues.
If the XML API being used doesn't support DOCTYPEs, the tool may drop DOCTYPEs altogether.
If the XML API doesn't support attributes in no namespace that are named "xmlns", attributes whose names start with "xmlns:", or
attributes in the XMLNS namespace, then the tool may drop such attributes.
The tool may annotate the output with any namespace declarations required for proper operation.
If the XML API being used restricts the allowable characters in the local names of elements and attributes, then the tool may map all element and attribute local names that the API wouldn't support to a set of names that are allowed, by replacing any character that isn't supported with the uppercase letter U and the six digits of the character's code point when expressed in hexadecimal, using digits 0-9 and capital letters A-F as the symbols, in increasing numeric order.
If the XML API restricts comments from having two consecutive U+002D HYPHEN-MINUS characters (--), the tool may insert a single U+0020 SPACE character between any such offending characters.
If the XML API restricts comments from ending in a U+002D HYPHEN-MINUS character (-), the tool may insert a single U+0020 SPACE character at the end of such comments.
If the XML API restricts allowed characters in character data, attribute values, or comments, the tool may replace any U+000C FORM FEED (FF) character with a U+0020 SPACE character, and any other literal non-XML character with a U+FFFD REPLACEMENT CHARACTER.
If the tool has no way to convey out-of-band information, then the tool may drop the following information:
form
element ancestor (use of the form element pointer in the parser)template elements.This section is non-normative.
This section examines some erroneous markup and discusses how the HTML parser handles these cases.
This section is non-normative.
The most-often discussed example of erroneous markup is as follows:
The parsing of this markup is straightforward up to the "3". At this point, the DOM looks like this:
Here, the stack of open elements has five elements on it: html,
body, p, b, and i. The list of active
formatting elements just has two: b and i. The insertion
mode is "in body".
Upon receiving the end tag token with the tag name "b", the "adoption
agency algorithm" is invoked. This is a simple case, in that the formattingElement
is the b element, and there is no furthest block.
Thus, the stack of open elements ends up with just three elements: html,
body, and p, while the list of active formatting elements
has just one: i. The DOM tree is unmodified at this point.
The next token is a character ("4"), triggers the reconstruction of the active formatting elements, in this case just
the i element. A new i element is thus created for the "4"
Text node. After the end tag token for the "i" is also received, and the "5"
Text node is inserted, the DOM looks as follows:
This section is non-normative.
A case similar to the previous one is the following:
Up to the "2" the parsing here is straightforward:
The interesting part is when the end tag token with the tag name "b" is parsed.
Before that token is seen, the stack of open elements has four elements on it:
html, body, b, and p. The list of active
formatting elements just has the one: b. The insertion mode is
"in body".
Upon receiving the end tag token with the tag name "b", the "adoption
agency algorithm" is invoked, as in the previous example. However, in this case, there
is a furthest block, namely the p element. Thus, this
time the adoption agency algorithm isn't skipped over.
The common ancestor is the body element. A conceptual
"bookmark" marks the position of the b in the list of active formatting
elements, but since that list has only one element in it, the bookmark won't have much
effect.
As the algorithm progresses, node ends up set to the formatting element
(b), and last node ends up set to the furthest
block (p).
The last node gets appended (moved) to the common ancestor, so that the DOM looks like:
A new b element is created, and the children of the p element are
moved to it:
Finally, the new b element is appended to the p element, so that the
DOM looks like:
The b element is removed from the list of active formatting elements
and the stack of open elements, so that when the "3" is parsed, it is appended to the
p element:
This section is non-normative.
Error handling in tables is, for historical reasons, especially strange. For example, consider the following markup:
The highlighted b element start tag is not allowed directly inside a table like
that, and the parser handles this case by placing the element before the table. (This is
called foster parenting.) This can be seen by examining the DOM tree
as it stands just after the table element's start tag has been seen:
...and then immediately after the b element start tag has been seen:
At this point, the stack of open elements has on it the elements
html, body, table, and b (in that order,
despite the resulting DOM tree); the list of active formatting elements just has the
b element in it; and the insertion mode is "in table".
The tr start tag causes the b element to be popped off the stack and
a tbody start tag to be implied; the tbody and tr elements
are then handled in a rather straight-forward manner, taking the parser through the "in table body" and "in row" insertion modes, after which the DOM looks as follows:
Here, the stack of open elements has on it the elements html,
body, table, tbody, and tr; the list of
active formatting elements still has the b element in it; and the
insertion mode is "in row".
The td element start tag token, after putting a td element on the
tree, puts a marker on the list of active
formatting elements (it also switches to the "in
cell" insertion mode).
The marker means that when the "aaa" character
tokens are seen, no b element is created to hold the resulting Text
node:
The end tags are handled in a straight-forward manner; after handling them, the stack of
open elements has on it the elements html, body,
table, and tbody; the list of active formatting elements
still has the b element in it (the marker
having been removed by the "td" end tag token); and the insertion mode is "in table body".
Thus it is that the "bbb" character tokens are found. These trigger the "in table text" insertion mode to be used (with the original
insertion mode set to "in table body").
The character tokens are collected, and when the next token (the table element end
tag) is seen, they are processed as a group. Since they are not all spaces, they are handled as
per the "anything else" rules in the "in table"
insertion mode, which defer to the "in body"
insertion mode but with foster parenting.
When the active formatting elements
are reconstructed, a b element is created and foster parented, and then the "bbb" Text node is appended to it:
The stack of open elements has on it the elements html,
body, table, tbody, and the new b (again, note
that this doesn't match the resulting tree!); the list of active formatting elements
has the new b element in it; and the insertion mode is still "in table body".
Had the character tokens been only ASCII whitespace instead of "bbb", then that
ASCII whitespace would just be appended to the tbody element.
Finally, the table is closed by a "table" end tag. This pops all the nodes from
the stack of open elements up to and including the table element, but it
doesn't affect the list of active formatting elements, so the "ccc" character tokens
after the table result in yet another b element being created, this time after the
table:
This section is non-normative.
Consider the following markup, which for this example we will assume is the document with
URL https://example.com/inner, being rendered as the content of
an iframe in another document with the URL https://example.com/outer:
Up to the first "script" end tag, before the script is parsed, the result is relatively straightforward:
After the script is parsed, though, the div element and its child
script element are gone:
They are, at this point, in the Document of the aforementioned outer
browsing context. However, the stack of open elements still contains
the div element.
Thus, when the second script element is parsed, it is inserted into the outer
Document object.
Those parsed into different Documents than the one the parser was created for do
not execute, so the first alert does not show.
Once the div element's end tag is parsed, the div element is popped
off the stack, and so the next script element is in the inner
Document:
This script does execute, resulting in an alert that says "https://example.com/inner".
This section is non-normative.
Elaborating on the example in the previous section, consider the case where the second
script element is an external script (i.e. one with a src attribute). Since the element was not in the parser's
Document when it was created, that external script is not even downloaded.
In a case where a script element with a src
attribute is parsed normally into its parser's Document, but while the external
script is being downloaded, the element is moved to another document, the script continues to
download, but does not execute.
This section is non-normative.
The following markup shows how nested formatting elements (such as b) get
collected and continue to be applied even as the elements they are contained in are closed, but
that excessive duplicates are thrown away.
The resulting DOM tree is as follows:
htmlhtmlNote how the second p element in the markup has no explicit b
elements, but in the resulting DOM, up to three of each kind of formatting element (in this case
three b elements with the class attribute, and two unadorned b elements)
get reconstructed before the element's "X".
Also note how this means that in the final paragraph only six b end tags are
needed to completely clear the list of active formatting elements, even though nine
b start tags have been seen up to this point.
For historical reasons, this algorithm does not round-trip an initial U+000A LINE FEED (LF)
character in pre, textarea, or listing elements, even
though (in the first two cases) the markup being round-tripped can be conforming. The HTML
parser will drop such a character during parsing, but this algorithm does not
serialize an extra U+000A LINE FEED (LF) character.
Because of the special role of the is attribute in signaling the creation of customized built-in elements, in that it provides a mechanism for parsed
HTML to set the element's is
value, we special-case its handling during serialization. This ensures that an element's
is value is preserved
through serialize-parse roundtrips.
This table lists the character reference names that are supported by HTML, and the code points to which they refer. It is referenced by the previous sections.
| Name | Character(s) | Glyph |
|---|---|---|
Aacute; | U+000C1 | Á |
Aacute | U+000C1 | Á |
aacute; | U+000E1 | á |
aacute | U+000E1 | á |
Abreve; | U+00102 | Ă |
abreve; | U+00103 | ă |
ac; | U+0223E | ∾ |
acd; | U+0223F | ∿ |
acE; | U+0223E U+00333 | ∾̳ |
Acirc; | U+000C2 | Â |
Acirc | U+000C2 | Â |
acirc; | U+000E2 | â |
acirc | U+000E2 | â |
acute; | U+000B4 | ´ |
acute | U+000B4 | ´ |
Acy; | U+00410 | А |
acy; | U+00430 | а |
AElig; | U+000C6 | Æ |
AElig | U+000C6 | Æ |
aelig; | U+000E6 | æ |
aelig | U+000E6 | æ |
af; | U+02061 | |
Afr; | U+1D504 | 𝔄 |
afr; | U+1D51E | 𝔞 |
Agrave; | U+000C0 | À |
Agrave | U+000C0 | À |
agrave; | U+000E0 | à |
agrave | U+000E0 | à |
alefsym; | U+02135 | ℵ |
aleph; | U+02135 | ℵ |
Alpha; | U+00391 | Α |
alpha; | U+003B1 | α |
Amacr; | U+00100 | Ā |
amacr; | U+00101 | ā |
amalg; | U+02A3F | ⨿ |
AMP; | U+00026 | & |
AMP | U+00026 | & |
amp; | U+00026 | & |
amp | U+00026 | & |
And; | U+02A53 | ⩓ |
and; | U+02227 | ∧ |
andand; | U+02A55 | ⩕ |
andd; | U+02A5C | ⩜ |
andslope; | U+02A58 | ⩘ |
andv; | U+02A5A | ⩚ |
ang; | U+02220 | ∠ |
ange; | U+029A4 | ⦤ |
angle; | U+02220 | ∠ |
angmsd; | U+02221 | ∡ |
angmsdaa; | U+029A8 | ⦨ |
angmsdab; | U+029A9 | ⦩ |
angmsdac; | U+029AA | ⦪ |
angmsdad; | U+029AB | ⦫ |
angmsdae; | U+029AC | ⦬ |
angmsdaf; | U+029AD | ⦭ |
angmsdag; | U+029AE | ⦮ |
angmsdah; | U+029AF | ⦯ |
angrt; | U+0221F | ∟ |
angrtvb; | U+022BE | ⊾ |
angrtvbd; | U+0299D | ⦝ |
angsph; | U+02222 | ∢ |
angst; | U+000C5 | Å |
angzarr; | U+0237C | ⍼ |
Aogon; | U+00104 | Ą |
aogon; | U+00105 | ą |
Aopf; | U+1D538 | 𝔸 |
aopf; | U+1D552 | 𝕒 |
ap; | U+02248 | ≈ |
apacir; | U+02A6F | ⩯ |
apE; | U+02A70 | ⩰ |
ape; | U+0224A | ≊ |
apid; | U+0224B | ≋ |
apos; | U+00027 | ' |
ApplyFunction; | U+02061 | |
approx; | U+02248 | ≈ |
approxeq; | U+0224A | ≊ |
Aring; | U+000C5 | Å |
Aring | U+000C5 | Å |
aring; | U+000E5 | å |
aring | U+000E5 | å |
Ascr; | U+1D49C | 𝒜 |
ascr; | U+1D4B6 | 𝒶 |
Assign; | U+02254 | ≔ |
ast; | U+0002A | * |
asymp; | U+02248 | ≈ |
asympeq; | U+0224D | ≍ |
Atilde; | U+000C3 | Ã |
Atilde | U+000C3 | Ã |
atilde; | U+000E3 | ã |
atilde | U+000E3 | ã |
Auml; | U+000C4 | Ä |
Auml | U+000C4 | Ä |
auml; | U+000E4 | ä |
auml | U+000E4 | ä |
awconint; | U+02233 | ∳ |
awint; | U+02A11 | ⨑ |
backcong; | U+0224C | ≌ |
backepsilon; | U+003F6 | ϶ |
backprime; | U+02035 | ‵ |
backsim; | U+0223D | ∽ |
backsimeq; | U+022CD | ⋍ |
Backslash; | U+02216 | ∖ |
Barv; | U+02AE7 | ⫧ |
barvee; | U+022BD | ⊽ |
Barwed; | U+02306 | ⌆ |
barwed; | U+02305 | ⌅ |
barwedge; | U+02305 | ⌅ |
bbrk; | U+023B5 | ⎵ |
bbrktbrk; | U+023B6 | ⎶ |
bcong; | U+0224C | ≌ |
Bcy; | U+00411 | Б |
bcy; | U+00431 | б |
bdquo; | U+0201E | „ |
becaus; | U+02235 | ∵ |
Because; | U+02235 | ∵ |
because; | U+02235 | ∵ |
bemptyv; | U+029B0 | ⦰ |
bepsi; | U+003F6 | ϶ |
bernou; | U+0212C | ℬ |
Bernoullis; | U+0212C | ℬ |
Beta; | U+00392 | Β |
beta; | U+003B2 | β |
beth; | U+02136 | ℶ |
between; | U+0226C | ≬ |
Bfr; | U+1D505 | 𝔅 |
bfr; | U+1D51F | 𝔟 |
bigcap; | U+022C2 | ⋂ |
bigcirc; | U+025EF | ◯ |
bigcup; | U+022C3 | ⋃ |
bigodot; | U+02A00 | ⨀ |
bigoplus; | U+02A01 | ⨁ |
bigotimes; | U+02A02 | ⨂ |
bigsqcup; | U+02A06 | ⨆ |
bigstar; | U+02605 | ★ |
bigtriangledown; | U+025BD | ▽ |
bigtriangleup; | U+025B3 | △ |
biguplus; | U+02A04 | ⨄ |
bigvee; | U+022C1 | ⋁ |
bigwedge; | U+022C0 | ⋀ |
bkarow; | U+0290D | ⤍ |
blacklozenge; | U+029EB | ⧫ |
blacksquare; | U+025AA | ▪ |
blacktriangle; | U+025B4 | ▴ |
blacktriangledown; | U+025BE | ▾ |
blacktriangleleft; | U+025C2 | ◂ |
blacktriangleright; | U+025B8 | ▸ |
blank; | U+02423 | ␣ |
blk12; | U+02592 | ▒ |
blk14; | U+02591 | ░ |
blk34; | U+02593 | ▓ |
block; | U+02588 | █ |
bne; | U+0003D U+020E5 | =⃥ |
bnequiv; | U+02261 U+020E5 | ≡⃥ |
bNot; | U+02AED | ⫭ |
bnot; | U+02310 | ⌐ |
Bopf; | U+1D539 | 𝔹 |
bopf; | U+1D553 | 𝕓 |
bot; | U+022A5 | ⊥ |
bottom; | U+022A5 | ⊥ |
bowtie; | U+022C8 | ⋈ |
boxbox; | U+029C9 | ⧉ |
boxDL; | U+02557 | ╗ |
boxDl; | U+02556 | ╖ |
boxdL; | U+02555 | ╕ |
boxdl; | U+02510 | ┐ |
boxDR; | U+02554 | ╔ |
boxDr; | U+02553 | ╓ |
boxdR; | U+02552 | ╒ |
boxdr; | U+0250C | ┌ |
boxH; | U+02550 | ═ |
boxh; | U+02500 | ─ |
boxHD; | U+02566 | ╦ |
boxHd; | U+02564 | ╤ |
boxhD; | U+02565 | ╥ |
boxhd; | U+0252C | ┬ |
boxHU; | U+02569 | ╩ |
boxHu; | U+02567 | ╧ |
boxhU; | U+02568 | ╨ |
boxhu; | U+02534 | ┴ |
boxminus; | U+0229F | ⊟ |
boxplus; | U+0229E | ⊞ |
boxtimes; | U+022A0 | ⊠ |
boxUL; | U+0255D | ╝ |
boxUl; | U+0255C | ╜ |
boxuL; | U+0255B | ╛ |
boxul; | U+02518 | ┘ |
boxUR; | U+0255A | ╚ |
boxUr; | U+02559 | ╙ |
boxuR; | U+02558 | ╘ |
boxur; | U+02514 | └ |
boxV; | U+02551 | ║ |
boxv; | U+02502 | │ |
boxVH; | U+0256C | ╬ |
boxVh; | U+0256B | ╫ |
boxvH; | U+0256A | ╪ |
boxvh; | U+0253C | ┼ |
boxVL; | U+02563 | ╣ |
boxVl; | U+02562 | ╢ |
boxvL; | U+02561 | ╡ |
boxvl; | U+02524 | ┤ |
boxVR; | U+02560 | ╠ |
boxVr; | U+0255F | ╟ |
boxvR; | U+0255E | ╞ |
boxvr; | U+0251C | ├ |
bprime; | U+02035 | ‵ |
Breve; | U+002D8 | ˘ |
breve; | U+002D8 | ˘ |
brvbar; | U+000A6 | ¦ |
brvbar | U+000A6 | ¦ |
Bscr; | U+0212C | ℬ |
bscr; | U+1D4B7 | 𝒷 |
bsemi; | U+0204F | ⁏ |
bsim; | U+0223D | ∽ |
bsime; | U+022CD | ⋍ |
bsol; | U+0005C | \ |
bsolb; | U+029C5 | ⧅ |
bsolhsub; | U+027C8 | ⟈ |
bull; | U+02022 | • |
bullet; | U+02022 | • |
bump; | U+0224E | ≎ |
bumpE; | U+02AAE | ⪮ |
bumpe; | U+0224F | ≏ |
Bumpeq; | U+0224E | ≎ |
bumpeq; | U+0224F | ≏ |
Cacute; | U+00106 | Ć |
cacute; | U+00107 | ć |
Cap; | U+022D2 | ⋒ |
cap; | U+02229 | ∩ |
capand; | U+02A44 | ⩄ |
capbrcup; | U+02A49 | ⩉ |
capcap; | U+02A4B | ⩋ |
capcup; | U+02A47 | ⩇ |
capdot; | U+02A40 | ⩀ |
CapitalDifferentialD; | U+02145 | ⅅ |
caps; | U+02229 U+0FE00 | ∩︀ |
caret; | U+02041 | ⁁ |
caron; | U+002C7 | ˇ |
Cayleys; | U+0212D | ℭ |
ccaps; | U+02A4D | ⩍ |
Ccaron; | U+0010C | Č |
ccaron; | U+0010D | č |
Ccedil; | U+000C7 | Ç |
Ccedil | U+000C7 | Ç |
ccedil; | U+000E7 | ç |
ccedil | U+000E7 | ç |
Ccirc; | U+00108 | Ĉ |
ccirc; | U+00109 | ĉ |
Cconint; | U+02230 | ∰ |
ccups; | U+02A4C | ⩌ |
ccupssm; | U+02A50 | ⩐ |
Cdot; | U+0010A | Ċ |
cdot; | U+0010B | ċ |
cedil; | U+000B8 | ¸ |
cedil | U+000B8 | ¸ |
Cedilla; | U+000B8 | ¸ |
cemptyv; | U+029B2 | ⦲ |
cent; | U+000A2 | ¢ |
cent | U+000A2 | ¢ |
CenterDot; | U+000B7 | · |
centerdot; | U+000B7 | · |
Cfr; | U+0212D | ℭ |
cfr; | U+1D520 | 𝔠 |
CHcy; | U+00427 | Ч |
chcy; | U+00447 | ч |
check; | U+02713 | ✓ |
checkmark; | U+02713 | ✓ |
Chi; | U+003A7 | Χ |
chi; | U+003C7 | χ |
cir; | U+025CB | ○ |
circ; | U+002C6 | ˆ |
circeq; | U+02257 | ≗ |
circlearrowleft; | U+021BA | ↺ |
circlearrowright; | U+021BB | ↻ |
circledast; | U+0229B | ⊛ |
circledcirc; | U+0229A | ⊚ |
circleddash; | U+0229D | ⊝ |
CircleDot; | U+02299 | ⊙ |
circledR; | U+000AE | ® |
circledS; | U+024C8 | Ⓢ |
CircleMinus; | U+02296 | ⊖ |
CirclePlus; | U+02295 | ⊕ |
CircleTimes; | U+02297 | ⊗ |
cirE; | U+029C3 | ⧃ |
cire; | U+02257 | ≗ |
cirfnint; | U+02A10 | ⨐ |
cirmid; | U+02AEF | ⫯ |
cirscir; | U+029C2 | ⧂ |
ClockwiseContourIntegral; | U+02232 | ∲ |
CloseCurlyDoubleQuote; | U+0201D | ” |
CloseCurlyQuote; | U+02019 | ’ |
clubs; | U+02663 | ♣ |
clubsuit; | U+02663 | ♣ |
Colon; | U+02237 | ∷ |
colon; | U+0003A | : |
Colone; | U+02A74 | ⩴ |
colone; | U+02254 | ≔ |
coloneq; | U+02254 | ≔ |
comma; | U+0002C | , |
commat; | U+00040 | @ |
comp; | U+02201 | ∁ |
compfn; | U+02218 | ∘ |
complement; | U+02201 | ∁ |
complexes; | U+02102 | ℂ |
cong; | U+02245 | ≅ |
congdot; | U+02A6D | ⩭ |
Congruent; | U+02261 | ≡ |
Conint; | U+0222F | ∯ |
conint; | U+0222E | ∮ |
ContourIntegral; | U+0222E | ∮ |
Copf; | U+02102 | ℂ |
copf; | U+1D554 | 𝕔 |
coprod; | U+02210 | ∐ |
Coproduct; | U+02210 | ∐ |
COPY; | U+000A9 | © |
COPY | U+000A9 | © |
copy; | U+000A9 | © |
copy | U+000A9 | © |
copysr; | U+02117 | ℗ |
CounterClockwiseContourIntegral; | U+02233 | ∳ |
crarr; | U+021B5 | ↵ |
Cross; | U+02A2F | ⨯ |
cross; | U+02717 | ✗ |
Cscr; | U+1D49E | 𝒞 |
cscr; | U+1D4B8 | 𝒸 |
csub; | U+02ACF | ⫏ |
csube; | U+02AD1 | ⫑ |
csup; | U+02AD0 | ⫐ |
csupe; | U+02AD2 | ⫒ |
ctdot; | U+022EF | ⋯ |
cudarrl; | U+02938 | ⤸ |
cudarrr; | U+02935 | ⤵ |
cuepr; | U+022DE | ⋞ |
cuesc; | U+022DF | ⋟ |
cularr; | U+021B6 | ↶ |
cularrp; | U+0293D | ⤽ |
Cup; | U+022D3 | ⋓ |
cup; | U+0222A | ∪ |
cupbrcap; | U+02A48 | ⩈ |
CupCap; | U+0224D | ≍ |
cupcap; | U+02A46 | ⩆ |
cupcup; | U+02A4A | ⩊ |
cupdot; | U+0228D | ⊍ |
cupor; | U+02A45 | ⩅ |
cups; | U+0222A U+0FE00 | ∪︀ |
curarr; | U+021B7 | ↷ |
curarrm; | U+0293C | ⤼ |
curlyeqprec; | U+022DE | ⋞ |
curlyeqsucc; | U+022DF | ⋟ |
curlyvee; | U+022CE | ⋎ |
curlywedge; | U+022CF | ⋏ |
curren; | U+000A4 | ¤ |
curren | U+000A4 | ¤ |
curvearrowleft; | U+021B6 | ↶ |
curvearrowright; | U+021B7 | ↷ |
cuvee; | U+022CE | ⋎ |
cuwed; | U+022CF | ⋏ |
cwconint; | U+02232 | ∲ |
cwint; | U+02231 | ∱ |
cylcty; | U+0232D | ⌭ |
Dagger; | U+02021 | ‡ |
dagger; | U+02020 | † |
daleth; | U+02138 | ℸ |
Darr; | U+021A1 | ↡ |
dArr; | U+021D3 | ⇓ |
darr; | U+02193 | ↓ |
dash; | U+02010 | ‐ |
Dashv; | U+02AE4 | ⫤ |
dashv; | U+022A3 | ⊣ |
dbkarow; | U+0290F | ⤏ |
dblac; | U+002DD | ˝ |
Dcaron; | U+0010E | Ď |
dcaron; | U+0010F | ď |
Dcy; | U+00414 | Д |
dcy; | U+00434 | д |
DD; | U+02145 | ⅅ |
dd; | U+02146 | ⅆ |
ddagger; | U+02021 | ‡ |
ddarr; | U+021CA | ⇊ |
DDotrahd; | U+02911 | ⤑ |
ddotseq; | U+02A77 | ⩷ |
deg; | U+000B0 | ° |
deg | U+000B0 | ° |
Del; | U+02207 | ∇ |
Delta; | U+00394 | Δ |
delta; | U+003B4 | δ |
demptyv; | U+029B1 | ⦱ |
dfisht; | U+0297F | ⥿ |
Dfr; | U+1D507 | 𝔇 |
dfr; | U+1D521 | 𝔡 |
dHar; | U+02965 | ⥥ |
dharl; | U+021C3 | ⇃ |
dharr; | U+021C2 | ⇂ |
DiacriticalAcute; | U+000B4 | ´ |
DiacriticalDot; | U+002D9 | ˙ |
DiacriticalDoubleAcute; | U+002DD | ˝ |
DiacriticalGrave; | U+00060 | ` |
DiacriticalTilde; | U+002DC | ˜ |
diam; | U+022C4 | ⋄ |
Diamond; | U+022C4 | ⋄ |
diamond; | U+022C4 | ⋄ |
diamondsuit; | U+02666 | ♦ |
diams; | U+02666 | ♦ |
die; | U+000A8 | ¨ |
DifferentialD; | U+02146 | ⅆ |
digamma; | U+003DD | ϝ |
disin; | U+022F2 | ⋲ |
div; | U+000F7 | ÷ |
divide; | U+000F7 | ÷ |
divide | U+000F7 | ÷ |
divideontimes; | U+022C7 | ⋇ |
divonx; | U+022C7 | ⋇ |
DJcy; | U+00402 | Ђ |
djcy; | U+00452 | ђ |
dlcorn; | U+0231E | ⌞ |
dlcrop; | U+0230D | ⌍ |
dollar; | U+00024 | $ |
Dopf; | U+1D53B | 𝔻 |
dopf; | U+1D555 | 𝕕 |
Dot; | U+000A8 | ¨ |
dot; | U+002D9 | ˙ |
DotDot; | U+020DC | ◌⃜ |
doteq; | U+02250 | ≐ |
doteqdot; | U+02251 | ≑ |
DotEqual; | U+02250 | ≐ |
dotminus; | U+02238 | ∸ |
dotplus; | U+02214 | ∔ |
dotsquare; | U+022A1 | ⊡ |
doublebarwedge; | U+02306 | ⌆ |
DoubleContourIntegral; | U+0222F | ∯ |
DoubleDot; | U+000A8 | ¨ |
DoubleDownArrow; | U+021D3 | ⇓ |
DoubleLeftArrow; | U+021D0 | ⇐ |
DoubleLeftRightArrow; | U+021D4 | ⇔ |
DoubleLeftTee; | U+02AE4 | ⫤ |
DoubleLongLeftArrow; | U+027F8 | ⟸ |
DoubleLongLeftRightArrow; | U+027FA | ⟺ |
DoubleLongRightArrow; | U+027F9 | ⟹ |
DoubleRightArrow; | U+021D2 | ⇒ |
DoubleRightTee; | U+022A8 | ⊨ |
DoubleUpArrow; | U+021D1 | ⇑ |
DoubleUpDownArrow; | U+021D5 | ⇕ |
DoubleVerticalBar; | U+02225 | ∥ |
DownArrow; | U+02193 | ↓ |
Downarrow; | U+021D3 | ⇓ |
downarrow; | U+02193 | ↓ |
DownArrowBar; | U+02913 | ⤓ |
DownArrowUpArrow; | U+021F5 | ⇵ |
DownBreve; | U+00311 | ◌̑ |
downdownarrows; | U+021CA | ⇊ |
downharpoonleft; | U+021C3 | ⇃ |
downharpoonright; | U+021C2 | ⇂ |
DownLeftRightVector; | U+02950 | ⥐ |
DownLeftTeeVector; | U+0295E | ⥞ |
DownLeftVector; | U+021BD | ↽ |
DownLeftVectorBar; | U+02956 | ⥖ |
DownRightTeeVector; | U+0295F | ⥟ |
DownRightVector; | U+021C1 | ⇁ |
DownRightVectorBar; | U+02957 | ⥗ |
DownTee; | U+022A4 | ⊤ |
DownTeeArrow; | U+021A7 | ↧ |
drbkarow; | U+02910 | ⤐ |
drcorn; | U+0231F | ⌟ |
drcrop; | U+0230C | ⌌ |
Dscr; | U+1D49F | 𝒟 |
dscr; | U+1D4B9 | 𝒹 |
DScy; | U+00405 | Ѕ |
dscy; | U+00455 | ѕ |
dsol; | U+029F6 | ⧶ |
Dstrok; | U+00110 | Đ |
dstrok; | U+00111 | đ |
dtdot; | U+022F1 | ⋱ |
dtri; | U+025BF | ▿ |
dtrif; | U+025BE | ▾ |
duarr; | U+021F5 | ⇵ |
duhar; | U+0296F | ⥯ |
dwangle; | U+029A6 | ⦦ |
DZcy; | U+0040F | Џ |
dzcy; | U+0045F | џ |
dzigrarr; | U+027FF | ⟿ |
Eacute; | U+000C9 | É |
Eacute | U+000C9 | É |
eacute; | U+000E9 | é |
eacute | U+000E9 | é |
easter; | U+02A6E | ⩮ |
Ecaron; | U+0011A | Ě |
ecaron; | U+0011B | ě |
ecir; | U+02256 | ≖ |
Ecirc; | U+000CA | Ê |
Ecirc | U+000CA | Ê |
ecirc; | U+000EA | ê |
ecirc | U+000EA | ê |
ecolon; | U+02255 | ≕ |
Ecy; | U+0042D | Э |
ecy; | U+0044D | э |
eDDot; | U+02A77 | ⩷ |
Edot; | U+00116 | Ė |
eDot; | U+02251 | ≑ |
edot; | U+00117 | ė |
ee; | U+02147 | ⅇ |
efDot; | U+02252 | ≒ |
Efr; | U+1D508 | 𝔈 |
efr; | U+1D522 | 𝔢 |
eg; | U+02A9A | ⪚ |
Egrave; | U+000C8 | È |
Egrave | U+000C8 | È |
egrave; | U+000E8 | è |
egrave | U+000E8 | è |
egs; | U+02A96 | ⪖ |
egsdot; | U+02A98 | ⪘ |
el; | U+02A99 | ⪙ |
Element; | U+02208 | ∈ |
elinters; | U+023E7 | ⏧ |
ell; | U+02113 | ℓ |
els; | U+02A95 | ⪕ |
elsdot; | U+02A97 | ⪗ |
Emacr; | U+00112 | Ē |
emacr; | U+00113 | ē |
empty; | U+02205 | ∅ |
emptyset; | U+02205 | ∅ |
EmptySmallSquare; | U+025FB | ◻ |
emptyv; | U+02205 | ∅ |
EmptyVerySmallSquare; | U+025AB | ▫ |
emsp; | U+02003 | |
emsp13; | U+02004 | |
emsp14; | U+02005 | |
ENG; | U+0014A | Ŋ |
eng; | U+0014B | ŋ |
ensp; | U+02002 | |
Eogon; | U+00118 | Ę |
eogon; | U+00119 | ę |
Eopf; | U+1D53C | 𝔼 |
eopf; | U+1D556 | 𝕖 |
epar; | U+022D5 | ⋕ |
eparsl; | U+029E3 | ⧣ |
eplus; | U+02A71 | ⩱ |
epsi; | U+003B5 | ε |
Epsilon; | U+00395 | Ε |
epsilon; | U+003B5 | ε |
epsiv; | U+003F5 | ϵ |
eqcirc; | U+02256 | ≖ |
eqcolon; | U+02255 | ≕ |
eqsim; | U+02242 | ≂ |
eqslantgtr; | U+02A96 | ⪖ |
eqslantless; | U+02A95 | ⪕ |
Equal; | U+02A75 | ⩵ |
equals; | U+0003D | = |
EqualTilde; | U+02242 | ≂ |
equest; | U+0225F | ≟ |
Equilibrium; | U+021CC | ⇌ |
equiv; | U+02261 | ≡ |
equivDD; | U+02A78 | ⩸ |
eqvparsl; | U+029E5 | ⧥ |
erarr; | U+02971 | ⥱ |
erDot; | U+02253 | ≓ |
Escr; | U+02130 | ℰ |
escr; | U+0212F | ℯ |
esdot; | U+02250 | ≐ |
Esim; | U+02A73 | ⩳ |
esim; | U+02242 | ≂ |
Eta; | U+00397 | Η |
eta; | U+003B7 | η |
ETH; | U+000D0 | Ð |
ETH | U+000D0 | Ð |
eth; | U+000F0 | ð |
eth | U+000F0 | ð |
Euml; | U+000CB | Ë |
Euml | U+000CB | Ë |
euml; | U+000EB | ë |
euml | U+000EB | ë |
euro; | U+020AC | € |
excl; | U+00021 | ! |
exist; | U+02203 | ∃ |
Exists; | U+02203 | ∃ |
expectation; | U+02130 | ℰ |
ExponentialE; | U+02147 | ⅇ |
exponentiale; | U+02147 | ⅇ |
fallingdotseq; | U+02252 | ≒ |
Fcy; | U+00424 | Ф |
fcy; | U+00444 | ф |
female; | U+02640 | ♀ |
ffilig; | U+0FB03 | ffi |
fflig; | U+0FB00 | ff |
ffllig; | U+0FB04 | ffl |
Ffr; | U+1D509 | 𝔉 |
ffr; | U+1D523 | 𝔣 |
filig; | U+0FB01 | fi |
FilledSmallSquare; | U+025FC | ◼ |
FilledVerySmallSquare; | U+025AA | ▪ |
fjlig; | U+00066 U+0006A | fj |
flat; | U+0266D | ♭ |
fllig; | U+0FB02 | fl |
fltns; | U+025B1 | ▱ |
fnof; | U+00192 | ƒ |
Fopf; | U+1D53D | 𝔽 |
fopf; | U+1D557 | 𝕗 |
ForAll; | U+02200 | ∀ |
forall; | U+02200 | ∀ |
fork; | U+022D4 | ⋔ |
forkv; | U+02AD9 | ⫙ |
Fouriertrf; | U+02131 | ℱ |
fpartint; | U+02A0D | ⨍ |
frac12; | U+000BD | ½ |
frac12 | U+000BD | ½ |
frac13; | U+02153 | ⅓ |
frac14; | U+000BC | ¼ |
frac14 | U+000BC | ¼ |
frac15; | U+02155 | ⅕ |
frac16; | U+02159 | ⅙ |
frac18; | U+0215B | ⅛ |
frac23; | U+02154 | ⅔ |
frac25; | U+02156 | ⅖ |
frac34; | U+000BE | ¾ |
frac34 | U+000BE | ¾ |
frac35; | U+02157 | ⅗ |
frac38; | U+0215C | ⅜ |
frac45; | U+02158 | ⅘ |
frac56; | U+0215A | ⅚ |
frac58; | U+0215D | ⅝ |
frac78; | U+0215E | ⅞ |
frasl; | U+02044 | ⁄ |
frown; | U+02322 | ⌢ |
Fscr; | U+02131 | ℱ |
fscr; | U+1D4BB | 𝒻 |
gacute; | U+001F5 | ǵ |
Gamma; | U+00393 | Γ |
gamma; | U+003B3 | γ |
Gammad; | U+003DC | Ϝ |
gammad; | U+003DD | ϝ |
gap; | U+02A86 | ⪆ |
Gbreve; | U+0011E | Ğ |
gbreve; | U+0011F | ğ |
Gcedil; | U+00122 | Ģ |
Gcirc; | U+0011C | Ĝ |
gcirc; | U+0011D | ĝ |
Gcy; | U+00413 | Г |
gcy; | U+00433 | г |
Gdot; | U+00120 | Ġ |
gdot; | U+00121 | ġ |
gE; | U+02267 | ≧ |
ge; | U+02265 | ≥ |
gEl; | U+02A8C | ⪌ |
gel; | U+022DB | ⋛ |
geq; | U+02265 | ≥ |
geqq; | U+02267 | ≧ |
geqslant; | U+02A7E | ⩾ |
ges; | U+02A7E | ⩾ |
gescc; | U+02AA9 | ⪩ |
gesdot; | U+02A80 | ⪀ |
gesdoto; | U+02A82 | ⪂ |
gesdotol; | U+02A84 | ⪄ |
gesl; | U+022DB U+0FE00 | ⋛︀ |
gesles; | U+02A94 | ⪔ |
Gfr; | U+1D50A | 𝔊 |
gfr; | U+1D524 | 𝔤 |
Gg; | U+022D9 | ⋙ |
gg; | U+0226B | ≫ |
ggg; | U+022D9 | ⋙ |
gimel; | U+02137 | ℷ |
GJcy; | U+00403 | Ѓ |
gjcy; | U+00453 | ѓ |
gl; | U+02277 | ≷ |
gla; | U+02AA5 | ⪥ |
glE; | U+02A92 | ⪒ |
glj; | U+02AA4 | ⪤ |
gnap; | U+02A8A | ⪊ |
gnapprox; | U+02A8A | ⪊ |
gnE; | U+02269 | ≩ |
gne; | U+02A88 | ⪈ |
gneq; | U+02A88 | ⪈ |
gneqq; | U+02269 | ≩ |
gnsim; | U+022E7 | ⋧ |
Gopf; | U+1D53E | 𝔾 |
gopf; | U+1D558 | 𝕘 |
grave; | U+00060 | ` |
GreaterEqual; | U+02265 | ≥ |
GreaterEqualLess; | U+022DB | ⋛ |
GreaterFullEqual; | U+02267 | ≧ |
GreaterGreater; | U+02AA2 | ⪢ |
GreaterLess; | U+02277 | ≷ |
GreaterSlantEqual; | U+02A7E | ⩾ |
GreaterTilde; | U+02273 | ≳ |
Gscr; | U+1D4A2 | 𝒢 |
gscr; | U+0210A | ℊ |
gsim; | U+02273 | ≳ |
gsime; | U+02A8E | ⪎ |
gsiml; | U+02A90 | ⪐ |
GT; | U+0003E | > |
GT | U+0003E | > |
Gt; | U+0226B | ≫ |
gt; | U+0003E | > |
gt | U+0003E | > |
gtcc; | U+02AA7 | ⪧ |
gtcir; | U+02A7A | ⩺ |
gtdot; | U+022D7 | ⋗ |
gtlPar; | U+02995 | ⦕ |
gtquest; | U+02A7C | ⩼ |
gtrapprox; | U+02A86 | ⪆ |
gtrarr; | U+02978 | ⥸ |
gtrdot; | U+022D7 | ⋗ |
gtreqless; | U+022DB | ⋛ |
gtreqqless; | U+02A8C | ⪌ |
gtrless; | U+02277 | ≷ |
gtrsim; | U+02273 | ≳ |
gvertneqq; | U+02269 U+0FE00 | ≩︀ |
gvnE; | U+02269 U+0FE00 | ≩︀ |
Hacek; | U+002C7 | ˇ |
hairsp; | U+0200A | |
half; | U+000BD | ½ |
hamilt; | U+0210B | ℋ |
HARDcy; | U+0042A | Ъ |
hardcy; | U+0044A | ъ |
hArr; | U+021D4 | ⇔ |
harr; | U+02194 | ↔ |
harrcir; | U+02948 | ⥈ |
harrw; | U+021AD | ↭ |
Hat; | U+0005E | ^ |
hbar; | U+0210F | ℏ |
Hcirc; | U+00124 | Ĥ |
hcirc; | U+00125 | ĥ |
hearts; | U+02665 | ♥ |
heartsuit; | U+02665 | ♥ |
hellip; | U+02026 | … |
hercon; | U+022B9 | ⊹ |
Hfr; | U+0210C | ℌ |
hfr; | U+1D525 | 𝔥 |
HilbertSpace; | U+0210B | ℋ |
hksearow; | U+02925 | ⤥ |
hkswarow; | U+02926 | ⤦ |
hoarr; | U+021FF | ⇿ |
homtht; | U+0223B | ∻ |
hookleftarrow; | U+021A9 | ↩ |
hookrightarrow; | U+021AA | ↪ |
Hopf; | U+0210D | ℍ |
hopf; | U+1D559 | 𝕙 |
horbar; | U+02015 | ― |
HorizontalLine; | U+02500 | ─ |
Hscr; | U+0210B | ℋ |
hscr; | U+1D4BD | 𝒽 |
hslash; | U+0210F | ℏ |
Hstrok; | U+00126 | Ħ |
hstrok; | U+00127 | ħ |
HumpDownHump; | U+0224E | ≎ |
HumpEqual; | U+0224F | ≏ |
hybull; | U+02043 | ⁃ |
hyphen; | U+02010 | ‐ |
Iacute; | U+000CD | Í |
Iacute | U+000CD | Í |
iacute; | U+000ED | í |
iacute | U+000ED | í |
ic; | U+02063 | |
Icirc; | U+000CE | Î |
Icirc | U+000CE | Î |
icirc; | U+000EE | î |
icirc | U+000EE | î |
Icy; | U+00418 | И |
icy; | U+00438 | и |
Idot; | U+00130 | İ |
IEcy; | U+00415 | Е |
iecy; | U+00435 | е |
iexcl; | U+000A1 | ¡ |
iexcl | U+000A1 | ¡ |
iff; | U+021D4 | ⇔ |
Ifr; | U+02111 | ℑ |
ifr; | U+1D526 | 𝔦 |
Igrave; | U+000CC | Ì |
Igrave | U+000CC | Ì |
igrave; | U+000EC | ì |
igrave | U+000EC | ì |
ii; | U+02148 | ⅈ |
iiiint; | U+02A0C | ⨌ |
iiint; | U+0222D | ∭ |
iinfin; | U+029DC | ⧜ |
iiota; | U+02129 | ℩ |
IJlig; | U+00132 | IJ |
ijlig; | U+00133 | ij |
Im; | U+02111 | ℑ |
Imacr; | U+0012A | Ī |
imacr; | U+0012B | ī |
image; | U+02111 | ℑ |
ImaginaryI; | U+02148 | ⅈ |
imagline; | U+02110 | ℐ |
imagpart; | U+02111 | ℑ |
imath; | U+00131 | ı |
imof; | U+022B7 | ⊷ |
imped; | U+001B5 | Ƶ |
Implies; | U+021D2 | ⇒ |
in; | U+02208 | ∈ |
incare; | U+02105 | ℅ |
infin; | U+0221E | ∞ |
infintie; | U+029DD | ⧝ |
inodot; | U+00131 | ı |
Int; | U+0222C | ∬ |
int; | U+0222B | ∫ |
intcal; | U+022BA | ⊺ |
integers; | U+02124 | ℤ |
Integral; | U+0222B | ∫ |
intercal; | U+022BA | ⊺ |
Intersection; | U+022C2 | ⋂ |
intlarhk; | U+02A17 | ⨗ |
intprod; | U+02A3C | ⨼ |
InvisibleComma; | U+02063 | |
InvisibleTimes; | U+02062 | |
IOcy; | U+00401 | Ё |
iocy; | U+00451 | ё |
Iogon; | U+0012E | Į |
iogon; | U+0012F | į |
Iopf; | U+1D540 | 𝕀 |
iopf; | U+1D55A | 𝕚 |
Iota; | U+00399 | Ι |
iota; | U+003B9 | ι |
iprod; | U+02A3C | ⨼ |
iquest; | U+000BF | ¿ |
iquest | U+000BF | ¿ |
Iscr; | U+02110 | ℐ |
iscr; | U+1D4BE | 𝒾 |
isin; | U+02208 | ∈ |
isindot; | U+022F5 | ⋵ |
isinE; | U+022F9 | ⋹ |
isins; | U+022F4 | ⋴ |
isinsv; | U+022F3 | ⋳ |
isinv; | U+02208 | ∈ |
it; | U+02062 | |
Itilde; | U+00128 | Ĩ |
itilde; | U+00129 | ĩ |
Iukcy; | U+00406 | І |
iukcy; | U+00456 | і |
Iuml; | U+000CF | Ï |
Iuml | U+000CF | Ï |
iuml; | U+000EF | ï |
iuml | U+000EF | ï |
Jcirc; | U+00134 | Ĵ |
jcirc; | U+00135 | ĵ |
Jcy; | U+00419 | Й |
jcy; | U+00439 | й |
Jfr; | U+1D50D | 𝔍 |
jfr; | U+1D527 | 𝔧 |
jmath; | U+00237 | ȷ |
Jopf; | U+1D541 | 𝕁 |
jopf; | U+1D55B | 𝕛 |
Jscr; | U+1D4A5 | 𝒥 |
jscr; | U+1D4BF | 𝒿 |
Jsercy; | U+00408 | Ј |
jsercy; | U+00458 | ј |
Jukcy; | U+00404 | Є |
jukcy; | U+00454 | є |
Kappa; | U+0039A | Κ |
kappa; | U+003BA | κ |
kappav; | U+003F0 | ϰ |
Kcedil; | U+00136 | Ķ |
kcedil; | U+00137 | ķ |
Kcy; | U+0041A | К |
kcy; | U+0043A | к |
Kfr; | U+1D50E | 𝔎 |
kfr; | U+1D528 | 𝔨 |
kgreen; | U+00138 | ĸ |
KHcy; | U+00425 | Х |
khcy; | U+00445 | х |
KJcy; | U+0040C | Ќ |
kjcy; | U+0045C | ќ |
Kopf; | U+1D542 | 𝕂 |
kopf; | U+1D55C | 𝕜 |
Kscr; | U+1D4A6 | 𝒦 |
kscr; | U+1D4C0 | 𝓀 |
lAarr; | U+021DA | ⇚ |
Lacute; | U+00139 | Ĺ |
lacute; | U+0013A | ĺ |
laemptyv; | U+029B4 | ⦴ |
lagran; | U+02112 | ℒ |
Lambda; | U+0039B | Λ |
lambda; | U+003BB | λ |
Lang; | U+027EA | ⟪ |
lang; | U+027E8 | ⟨ |
langd; | U+02991 | ⦑ |
langle; | U+027E8 | ⟨ |
lap; | U+02A85 | ⪅ |
Laplacetrf; | U+02112 | ℒ |
laquo; | U+000AB | « |
laquo | U+000AB | « |
Larr; | U+0219E | ↞ |
lArr; | U+021D0 | ⇐ |
larr; | U+02190 | ← |
larrb; | U+021E4 | ⇤ |
larrbfs; | U+0291F | ⤟ |
larrfs; | U+0291D | ⤝ |
larrhk; | U+021A9 | ↩ |
larrlp; | U+021AB | ↫ |
larrpl; | U+02939 | ⤹ |
larrsim; | U+02973 | ⥳ |
larrtl; | U+021A2 | ↢ |
lat; | U+02AAB | ⪫ |
lAtail; | U+0291B | ⤛ |
latail; | U+02919 | ⤙ |
late; | U+02AAD | ⪭ |
lates; | U+02AAD U+0FE00 | ⪭︀ |
lBarr; | U+0290E | ⤎ |
lbarr; | U+0290C | ⤌ |
lbbrk; | U+02772 | ❲ |
lbrace; | U+0007B | { |
lbrack; | U+0005B | [ |
lbrke; | U+0298B | ⦋ |
lbrksld; | U+0298F | ⦏ |
lbrkslu; | U+0298D | ⦍ |
Lcaron; | U+0013D | Ľ |
lcaron; | U+0013E | ľ |
Lcedil; | U+0013B | Ļ |
lcedil; | U+0013C | ļ |
lceil; | U+02308 | ⌈ |
lcub; | U+0007B | { |
Lcy; | U+0041B | Л |
lcy; | U+0043B | л |
ldca; | U+02936 | ⤶ |
ldquo; | U+0201C | “ |
ldquor; | U+0201E | „ |
ldrdhar; | U+02967 | ⥧ |
ldrushar; | U+0294B | ⥋ |
ldsh; | U+021B2 | ↲ |
lE; | U+02266 | ≦ |
le; | U+02264 | ≤ |
LeftAngleBracket; | U+027E8 | ⟨ |
LeftArrow; | U+02190 | ← |
Leftarrow; | U+021D0 | ⇐ |
leftarrow; | U+02190 | ← |
LeftArrowBar; | U+021E4 | ⇤ |
LeftArrowRightArrow; | U+021C6 | ⇆ |
leftarrowtail; | U+021A2 | ↢ |
LeftCeiling; | U+02308 | ⌈ |
LeftDoubleBracket; | U+027E6 | ⟦ |
LeftDownTeeVector; | U+02961 | ⥡ |
LeftDownVector; | U+021C3 | ⇃ |
LeftDownVectorBar; | U+02959 | ⥙ |
LeftFloor; | U+0230A | ⌊ |
leftharpoondown; | U+021BD | ↽ |
leftharpoonup; | U+021BC | ↼ |
leftleftarrows; | U+021C7 | ⇇ |
LeftRightArrow; | U+02194 | ↔ |
Leftrightarrow; | U+021D4 | ⇔ |
leftrightarrow; | U+02194 | ↔ |
leftrightarrows; | U+021C6 | ⇆ |
leftrightharpoons; | U+021CB | ⇋ |
leftrightsquigarrow; | U+021AD | ↭ |
LeftRightVector; | U+0294E | ⥎ |
LeftTee; | U+022A3 | ⊣ |
LeftTeeArrow; | U+021A4 | ↤ |
LeftTeeVector; | U+0295A | ⥚ |
leftthreetimes; | U+022CB | ⋋ |
LeftTriangle; | U+022B2 | ⊲ |
LeftTriangleBar; | U+029CF | ⧏ |
LeftTriangleEqual; | U+022B4 | ⊴ |
LeftUpDownVector; | U+02951 | ⥑ |
LeftUpTeeVector; | U+02960 | ⥠ |
LeftUpVector; | U+021BF | ↿ |
LeftUpVectorBar; | U+02958 | ⥘ |
LeftVector; | U+021BC | ↼ |
LeftVectorBar; | U+02952 | ⥒ |
lEg; | U+02A8B | ⪋ |
leg; | U+022DA | ⋚ |
leq; | U+02264 | ≤ |
leqq; | U+02266 | ≦ |
leqslant; | U+02A7D | ⩽ |
les; | U+02A7D | ⩽ |
lescc; | U+02AA8 | ⪨ |
lesdot; | U+02A7F | ⩿ |
lesdoto; | U+02A81 | ⪁ |
lesdotor; | U+02A83 | ⪃ |
lesg; | U+022DA U+0FE00 | ⋚︀ |
lesges; | U+02A93 | ⪓ |
lessapprox; | U+02A85 | ⪅ |
lessdot; | U+022D6 | ⋖ |
lesseqgtr; | U+022DA | ⋚ |
lesseqqgtr; | U+02A8B | ⪋ |
LessEqualGreater; | U+022DA | ⋚ |
LessFullEqual; | U+02266 | ≦ |
LessGreater; | U+02276 | ≶ |
lessgtr; | U+02276 | ≶ |
LessLess; | U+02AA1 | ⪡ |
lesssim; | U+02272 | ≲ |
LessSlantEqual; | U+02A7D | ⩽ |
LessTilde; | U+02272 | ≲ |
lfisht; | U+0297C | ⥼ |
lfloor; | U+0230A | ⌊ |
Lfr; | U+1D50F | 𝔏 |
lfr; | U+1D529 | 𝔩 |
lg; | U+02276 | ≶ |
lgE; | U+02A91 | ⪑ |
lHar; | U+02962 | ⥢ |
lhard; | U+021BD | ↽ |
lharu; | U+021BC | ↼ |
lharul; | U+0296A | ⥪ |
lhblk; | U+02584 | ▄ |
LJcy; | U+00409 | Љ |
ljcy; | U+00459 | љ |
Ll; | U+022D8 | ⋘ |
ll; | U+0226A | ≪ |
llarr; | U+021C7 | ⇇ |
llcorner; | U+0231E | ⌞ |
Lleftarrow; | U+021DA | ⇚ |
llhard; | U+0296B | ⥫ |
lltri; | U+025FA | ◺ |
Lmidot; | U+0013F | Ŀ |
lmidot; | U+00140 | ŀ |
lmoust; | U+023B0 | ⎰ |
lmoustache; | U+023B0 | ⎰ |
lnap; | U+02A89 | ⪉ |
lnapprox; | U+02A89 | ⪉ |
lnE; | U+02268 | ≨ |
lne; | U+02A87 | ⪇ |
lneq; | U+02A87 | ⪇ |
lneqq; | U+02268 | ≨ |
lnsim; | U+022E6 | ⋦ |
loang; | U+027EC | ⟬ |
loarr; | U+021FD | ⇽ |
lobrk; | U+027E6 | ⟦ |
LongLeftArrow; | U+027F5 | ⟵ |
Longleftarrow; | U+027F8 | ⟸ |
longleftarrow; | U+027F5 | ⟵ |
LongLeftRightArrow; | U+027F7 | ⟷ |
Longleftrightarrow; | U+027FA | ⟺ |
longleftrightarrow; | U+027F7 | ⟷ |
longmapsto; | U+027FC | ⟼ |
LongRightArrow; | U+027F6 | ⟶ |
Longrightarrow; | U+027F9 | ⟹ |
longrightarrow; | U+027F6 | ⟶ |
looparrowleft; | U+021AB | ↫ |
looparrowright; | U+021AC | ↬ |
lopar; | U+02985 | ⦅ |
Lopf; | U+1D543 | 𝕃 |
lopf; | U+1D55D | 𝕝 |
loplus; | U+02A2D | ⨭ |
lotimes; | U+02A34 | ⨴ |
lowast; | U+02217 | ∗ |
lowbar; | U+0005F | _ |
LowerLeftArrow; | U+02199 | ↙ |
LowerRightArrow; | U+02198 | ↘ |
loz; | U+025CA | ◊ |
lozenge; | U+025CA | ◊ |
lozf; | U+029EB | ⧫ |
lpar; | U+00028 | ( |
lparlt; | U+02993 | ⦓ |
lrarr; | U+021C6 | ⇆ |
lrcorner; | U+0231F | ⌟ |
lrhar; | U+021CB | ⇋ |
lrhard; | U+0296D | ⥭ |
lrm; | U+0200E | |
lrtri; | U+022BF | ⊿ |
lsaquo; | U+02039 | ‹ |
Lscr; | U+02112 | ℒ |
lscr; | U+1D4C1 | 𝓁 |
Lsh; | U+021B0 | ↰ |
lsh; | U+021B0 | ↰ |
lsim; | U+02272 | ≲ |
lsime; | U+02A8D | ⪍ |
lsimg; | U+02A8F | ⪏ |
lsqb; | U+0005B | [ |
lsquo; | U+02018 | ‘ |
lsquor; | U+0201A | ‚ |
Lstrok; | U+00141 | Ł |
lstrok; | U+00142 | ł |
LT; | U+0003C | < |
LT | U+0003C | < |
Lt; | U+0226A | ≪ |
lt; | U+0003C | < |
lt | U+0003C | < |
ltcc; | U+02AA6 | ⪦ |
ltcir; | U+02A79 | ⩹ |
ltdot; | U+022D6 | ⋖ |
lthree; | U+022CB | ⋋ |
ltimes; | U+022C9 | ⋉ |
ltlarr; | U+02976 | ⥶ |
ltquest; | U+02A7B | ⩻ |
ltri; | U+025C3 | ◃ |
ltrie; | U+022B4 | ⊴ |
ltrif; | U+025C2 | ◂ |
ltrPar; | U+02996 | ⦖ |
lurdshar; | U+0294A | ⥊ |
luruhar; | U+02966 | ⥦ |
lvertneqq; | U+02268 U+0FE00 | ≨︀ |
lvnE; | U+02268 U+0FE00 | ≨︀ |
macr; | U+000AF | ¯ |
macr | U+000AF | ¯ |
male; | U+02642 | ♂ |
malt; | U+02720 | ✠ |
maltese; | U+02720 | ✠ |
Map; | U+02905 | ⤅ |
map; | U+021A6 | ↦ |
mapsto; | U+021A6 | ↦ |
mapstodown; | U+021A7 | ↧ |
mapstoleft; | U+021A4 | ↤ |
mapstoup; | U+021A5 | ↥ |
marker; | U+025AE | ▮ |
mcomma; | U+02A29 | ⨩ |
Mcy; | U+0041C | М |
mcy; | U+0043C | м |
mdash; | U+02014 | — |
mDDot; | U+0223A | ∺ |
measuredangle; | U+02221 | ∡ |
MediumSpace; | U+0205F | |
Mellintrf; | U+02133 | ℳ |
Mfr; | U+1D510 | 𝔐 |
mfr; | U+1D52A | 𝔪 |
mho; | U+02127 | ℧ |
micro; | U+000B5 | µ |
micro | U+000B5 | µ |
mid; | U+02223 | ∣ |
midast; | U+0002A | * |
midcir; | U+02AF0 | ⫰ |
middot; | U+000B7 | · |
middot | U+000B7 | · |
minus; | U+02212 | − |
minusb; | U+0229F | ⊟ |
minusd; | U+02238 | ∸ |
minusdu; | U+02A2A | ⨪ |
MinusPlus; | U+02213 | ∓ |
mlcp; | U+02ADB | ⫛ |
mldr; | U+02026 | … |
mnplus; | U+02213 | ∓ |
models; | U+022A7 | ⊧ |
Mopf; | U+1D544 | 𝕄 |
mopf; | U+1D55E | 𝕞 |
mp; | U+02213 | ∓ |
Mscr; | U+02133 | ℳ |
mscr; | U+1D4C2 | 𝓂 |
mstpos; | U+0223E | ∾ |
Mu; | U+0039C | Μ |
mu; | U+003BC | μ |
multimap; | U+022B8 | ⊸ |
mumap; | U+022B8 | ⊸ |
nabla; | U+02207 | ∇ |
Nacute; | U+00143 | Ń |
nacute; | U+00144 | ń |
nang; | U+02220 U+020D2 | ∠⃒ |
nap; | U+02249 | ≉ |
napE; | U+02A70 U+00338 | ⩰̸ |
napid; | U+0224B U+00338 | ≋̸ |
napos; | U+00149 | ʼn |
napprox; | U+02249 | ≉ |
natur; | U+0266E | ♮ |
natural; | U+0266E | ♮ |
naturals; | U+02115 | ℕ |
nbsp; | U+000A0 | |
nbsp | U+000A0 | |
nbump; | U+0224E U+00338 | ≎̸ |
nbumpe; | U+0224F U+00338 | ≏̸ |
ncap; | U+02A43 | ⩃ |
Ncaron; | U+00147 | Ň |
ncaron; | U+00148 | ň |
Ncedil; | U+00145 | Ņ |
ncedil; | U+00146 | ņ |
ncong; | U+02247 | ≇ |
ncongdot; | U+02A6D U+00338 | ⩭̸ |
ncup; | U+02A42 | ⩂ |
Ncy; | U+0041D | Н |
ncy; | U+0043D | н |
ndash; | U+02013 | – |
ne; | U+02260 | ≠ |
nearhk; | U+02924 | ⤤ |
neArr; | U+021D7 | ⇗ |
nearr; | U+02197 | ↗ |
nearrow; | U+02197 | ↗ |
nedot; | U+02250 U+00338 | ≐̸ |
NegativeMediumSpace; | U+0200B | |
NegativeThickSpace; | U+0200B | |
NegativeThinSpace; | U+0200B | |
NegativeVeryThinSpace; | U+0200B | |
nequiv; | U+02262 | ≢ |
nesear; | U+02928 | ⤨ |
nesim; | U+02242 U+00338 | ≂̸ |
NestedGreaterGreater; | U+0226B | ≫ |
NestedLessLess; | U+0226A | ≪ |
NewLine; | U+0000A | ␊ |
nexist; | U+02204 | ∄ |
nexists; | U+02204 | ∄ |
Nfr; | U+1D511 | 𝔑 |
nfr; | U+1D52B | 𝔫 |
ngE; | U+02267 U+00338 | ≧̸ |
nge; | U+02271 | ≱ |
ngeq; | U+02271 | ≱ |
ngeqq; | U+02267 U+00338 | ≧̸ |
ngeqslant; | U+02A7E U+00338 | ⩾̸ |
nges; | U+02A7E U+00338 | ⩾̸ |
nGg; | U+022D9 U+00338 | ⋙̸ |
ngsim; | U+02275 | ≵ |
nGt; | U+0226B U+020D2 | ≫⃒ |
ngt; | U+0226F | ≯ |
ngtr; | U+0226F | ≯ |
nGtv; | U+0226B U+00338 | ≫̸ |
nhArr; | U+021CE | ⇎ |
nharr; | U+021AE | ↮ |
nhpar; | U+02AF2 | ⫲ |
ni; | U+0220B | ∋ |
nis; | U+022FC | ⋼ |
nisd; | U+022FA | ⋺ |
niv; | U+0220B | ∋ |
NJcy; | U+0040A | Њ |
njcy; | U+0045A | њ |
nlArr; | U+021CD | ⇍ |
nlarr; | U+0219A | ↚ |
nldr; | U+02025 | ‥ |
nlE; | U+02266 U+00338 | ≦̸ |
nle; | U+02270 | ≰ |
nLeftarrow; | U+021CD | ⇍ |
nleftarrow; | U+0219A | ↚ |
nLeftrightarrow; | U+021CE | ⇎ |
nleftrightarrow; | U+021AE | ↮ |
nleq; | U+02270 | ≰ |
nleqq; | U+02266 U+00338 | ≦̸ |
nleqslant; | U+02A7D U+00338 | ⩽̸ |
nles; | U+02A7D U+00338 | ⩽̸ |
nless; | U+0226E | ≮ |
nLl; | U+022D8 U+00338 | ⋘̸ |
nlsim; | U+02274 | ≴ |
nLt; | U+0226A U+020D2 | ≪⃒ |
nlt; | U+0226E | ≮ |
nltri; | U+022EA | ⋪ |
nltrie; | U+022EC | ⋬ |
nLtv; | U+0226A U+00338 | ≪̸ |
nmid; | U+02224 | ∤ |
NoBreak; | U+02060 | |
NonBreakingSpace; | U+000A0 | |
Nopf; | U+02115 | ℕ |
nopf; | U+1D55F | 𝕟 |
Not; | U+02AEC | ⫬ |
not; | U+000AC | ¬ |
not | U+000AC | ¬ |
NotCongruent; | U+02262 | ≢ |
NotCupCap; | U+0226D | ≭ |
NotDoubleVerticalBar; | U+02226 | ∦ |
NotElement; | U+02209 | ∉ |
NotEqual; | U+02260 | ≠ |
NotEqualTilde; | U+02242 U+00338 | ≂̸ |
NotExists; | U+02204 | ∄ |
NotGreater; | U+0226F | ≯ |
NotGreaterEqual; | U+02271 | ≱ |
NotGreaterFullEqual; | U+02267 U+00338 | ≧̸ |
NotGreaterGreater; | U+0226B U+00338 | ≫̸ |
NotGreaterLess; | U+02279 | ≹ |
NotGreaterSlantEqual; | U+02A7E U+00338 | ⩾̸ |
NotGreaterTilde; | U+02275 | ≵ |
NotHumpDownHump; | U+0224E U+00338 | ≎̸ |
NotHumpEqual; | U+0224F U+00338 | ≏̸ |
notin; | U+02209 | ∉ |
notindot; | U+022F5 U+00338 | ⋵̸ |
notinE; | U+022F9 U+00338 | ⋹̸ |
notinva; | U+02209 | ∉ |
notinvb; | U+022F7 | ⋷ |
notinvc; | U+022F6 | ⋶ |
NotLeftTriangle; | U+022EA | ⋪ |
NotLeftTriangleBar; | U+029CF U+00338 | ⧏̸ |
NotLeftTriangleEqual; | U+022EC | ⋬ |
NotLess; | U+0226E | ≮ |
NotLessEqual; | U+02270 | ≰ |
NotLessGreater; | U+02278 | ≸ |
NotLessLess; | U+0226A U+00338 | ≪̸ |
NotLessSlantEqual; | U+02A7D U+00338 | ⩽̸ |
NotLessTilde; | U+02274 | ≴ |
NotNestedGreaterGreater; | U+02AA2 U+00338 | ⪢̸ |
NotNestedLessLess; | U+02AA1 U+00338 | ⪡̸ |
notni; | U+0220C | ∌ |
notniva; | U+0220C | ∌ |
notnivb; | U+022FE | ⋾ |
notnivc; | U+022FD | ⋽ |
NotPrecedes; | U+02280 | ⊀ |
NotPrecedesEqual; | U+02AAF U+00338 | ⪯̸ |
NotPrecedesSlantEqual; | U+022E0 | ⋠ |
NotReverseElement; | U+0220C | ∌ |
NotRightTriangle; | U+022EB | ⋫ |
NotRightTriangleBar; | U+029D0 U+00338 | ⧐̸ |
NotRightTriangleEqual; | U+022ED | ⋭ |
NotSquareSubset; | U+0228F U+00338 | ⊏̸ |
NotSquareSubsetEqual; | U+022E2 | ⋢ |
NotSquareSuperset; | U+02290 U+00338 | ⊐̸ |
NotSquareSupersetEqual; | U+022E3 | ⋣ |
NotSubset; | U+02282 U+020D2 | ⊂⃒ |
NotSubsetEqual; | U+02288 | ⊈ |
NotSucceeds; | U+02281 | ⊁ |
NotSucceedsEqual; | U+02AB0 U+00338 | ⪰̸ |
NotSucceedsSlantEqual; | U+022E1 | ⋡ |
NotSucceedsTilde; | U+0227F U+00338 | ≿̸ |
NotSuperset; | U+02283 U+020D2 | ⊃⃒ |
NotSupersetEqual; | U+02289 | ⊉ |
NotTilde; | U+02241 | ≁ |
NotTildeEqual; | U+02244 | ≄ |
NotTildeFullEqual; | U+02247 | ≇ |
NotTildeTilde; | U+02249 | ≉ |
NotVerticalBar; | U+02224 | ∤ |
npar; | U+02226 | ∦ |
nparallel; | U+02226 | ∦ |
nparsl; | U+02AFD U+020E5 | ⫽⃥ |
npart; | U+02202 U+00338 | ∂̸ |
npolint; | U+02A14 | ⨔ |
npr; | U+02280 | ⊀ |
nprcue; | U+022E0 | ⋠ |
npre; | U+02AAF U+00338 | ⪯̸ |
nprec; | U+02280 | ⊀ |
npreceq; | U+02AAF U+00338 | ⪯̸ |
nrArr; | U+021CF | ⇏ |
nrarr; | U+0219B | ↛ |
nrarrc; | U+02933 U+00338 | ⤳̸ |
nrarrw; | U+0219D U+00338 | ↝̸ |
nRightarrow; | U+021CF | ⇏ |
nrightarrow; | U+0219B | ↛ |
nrtri; | U+022EB | ⋫ |
nrtrie; | U+022ED | ⋭ |
nsc; | U+02281 | ⊁ |
nsccue; | U+022E1 | ⋡ |
nsce; | U+02AB0 U+00338 | ⪰̸ |
Nscr; | U+1D4A9 | 𝒩 |
nscr; | U+1D4C3 | 𝓃 |
nshortmid; | U+02224 | ∤ |
nshortparallel; | U+02226 | ∦ |
nsim; | U+02241 | ≁ |
nsime; | U+02244 | ≄ |
nsimeq; | U+02244 | ≄ |
nsmid; | U+02224 | ∤ |
nspar; | U+02226 | ∦ |
nsqsube; | U+022E2 | ⋢ |
nsqsupe; | U+022E3 | ⋣ |
nsub; | U+02284 | ⊄ |
nsubE; | U+02AC5 U+00338 | ⫅̸ |
nsube; | U+02288 | ⊈ |
nsubset; | U+02282 U+020D2 | ⊂⃒ |
nsubseteq; | U+02288 | ⊈ |
nsubseteqq; | U+02AC5 U+00338 | ⫅̸ |
nsucc; | U+02281 | ⊁ |
nsucceq; | U+02AB0 U+00338 | ⪰̸ |
nsup; | U+02285 | ⊅ |
nsupE; | U+02AC6 U+00338 | ⫆̸ |
nsupe; | U+02289 | ⊉ |
nsupset; | U+02283 U+020D2 | ⊃⃒ |
nsupseteq; | U+02289 | ⊉ |
nsupseteqq; | U+02AC6 U+00338 | ⫆̸ |
ntgl; | U+02279 | ≹ |
Ntilde; | U+000D1 | Ñ |
Ntilde | U+000D1 | Ñ |
ntilde; | U+000F1 | ñ |
ntilde | U+000F1 | ñ |
ntlg; | U+02278 | ≸ |
ntriangleleft; | U+022EA | ⋪ |
ntrianglelefteq; | U+022EC | ⋬ |
ntriangleright; | U+022EB | ⋫ |
ntrianglerighteq; | U+022ED | ⋭ |
Nu; | U+0039D | Ν |
nu; | U+003BD | ν |
num; | U+00023 | # |
numero; | U+02116 | № |
numsp; | U+02007 | |
nvap; | U+0224D U+020D2 | ≍⃒ |
nVDash; | U+022AF | ⊯ |
nVdash; | U+022AE | ⊮ |
nvDash; | U+022AD | ⊭ |
nvdash; | U+022AC | ⊬ |
nvge; | U+02265 U+020D2 | ≥⃒ |
nvgt; | U+0003E U+020D2 | >⃒ |
nvHarr; | U+02904 | ⤄ |
nvinfin; | U+029DE | ⧞ |
nvlArr; | U+02902 | ⤂ |
nvle; | U+02264 U+020D2 | ≤⃒ |
nvlt; | U+0003C U+020D2 | <⃒ |
nvltrie; | U+022B4 U+020D2 | ⊴⃒ |
nvrArr; | U+02903 | ⤃ |
nvrtrie; | U+022B5 U+020D2 | ⊵⃒ |
nvsim; | U+0223C U+020D2 | ∼⃒ |
nwarhk; | U+02923 | ⤣ |
nwArr; | U+021D6 | ⇖ |
nwarr; | U+02196 | ↖ |
nwarrow; | U+02196 | ↖ |
nwnear; | U+02927 | ⤧ |
Oacute; | U+000D3 | Ó |
Oacute | U+000D3 | Ó |
oacute; | U+000F3 | ó |
oacute | U+000F3 | ó |
oast; | U+0229B | ⊛ |
ocir; | U+0229A | ⊚ |
Ocirc; | U+000D4 | Ô |
Ocirc | U+000D4 | Ô |
ocirc; | U+000F4 | ô |
ocirc | U+000F4 | ô |
Ocy; | U+0041E | О |
ocy; | U+0043E | о |
odash; | U+0229D | ⊝ |
Odblac; | U+00150 | Ő |
odblac; | U+00151 | ő |
odiv; | U+02A38 | ⨸ |
odot; | U+02299 | ⊙ |
odsold; | U+029BC | ⦼ |
OElig; | U+00152 | Œ |
oelig; | U+00153 | œ |
ofcir; | U+029BF | ⦿ |
Ofr; | U+1D512 | 𝔒 |
ofr; | U+1D52C | 𝔬 |
ogon; | U+002DB | ˛ |
Ograve; | U+000D2 | Ò |
Ograve | U+000D2 | Ò |
ograve; | U+000F2 | ò |
ograve | U+000F2 | ò |
ogt; | U+029C1 | ⧁ |
ohbar; | U+029B5 | ⦵ |
ohm; | U+003A9 | Ω |
oint; | U+0222E | ∮ |
olarr; | U+021BA | ↺ |
olcir; | U+029BE | ⦾ |
olcross; | U+029BB | ⦻ |
oline; | U+0203E | ‾ |
olt; | U+029C0 | ⧀ |
Omacr; | U+0014C | Ō |
omacr; | U+0014D | ō |
Omega; | U+003A9 | Ω |
omega; | U+003C9 | ω |
Omicron; | U+0039F | Ο |
omicron; | U+003BF | ο |
omid; | U+029B6 | ⦶ |
ominus; | U+02296 | ⊖ |
Oopf; | U+1D546 | 𝕆 |
oopf; | U+1D560 | 𝕠 |
opar; | U+029B7 | ⦷ |
OpenCurlyDoubleQuote; | U+0201C | “ |
OpenCurlyQuote; | U+02018 | ‘ |
operp; | U+029B9 | ⦹ |
oplus; | U+02295 | ⊕ |
Or; | U+02A54 | ⩔ |
or; | U+02228 | ∨ |
orarr; | U+021BB | ↻ |
ord; | U+02A5D | ⩝ |
order; | U+02134 | ℴ |
orderof; | U+02134 | ℴ |
ordf; | U+000AA | ª |
ordf | U+000AA | ª |
ordm; | U+000BA | º |
ordm | U+000BA | º |
origof; | U+022B6 | ⊶ |
oror; | U+02A56 | ⩖ |
orslope; | U+02A57 | ⩗ |
orv; | U+02A5B | ⩛ |
oS; | U+024C8 | Ⓢ |
Oscr; | U+1D4AA | 𝒪 |
oscr; | U+02134 | ℴ |
Oslash; | U+000D8 | Ø |
Oslash | U+000D8 | Ø |
oslash; | U+000F8 | ø |
oslash | U+000F8 | ø |
osol; | U+02298 | ⊘ |
Otilde; | U+000D5 | Õ |
Otilde | U+000D5 | Õ |
otilde; | U+000F5 | õ |
otilde | U+000F5 | õ |
Otimes; | U+02A37 | ⨷ |
otimes; | U+02297 | ⊗ |
otimesas; | U+02A36 | ⨶ |
Ouml; | U+000D6 | Ö |
Ouml | U+000D6 | Ö |
ouml; | U+000F6 | ö |
ouml | U+000F6 | ö |
ovbar; | U+0233D | ⌽ |
OverBar; | U+0203E | ‾ |
OverBrace; | U+023DE | ⏞ |
OverBracket; | U+023B4 | ⎴ |
OverParenthesis; | U+023DC | ⏜ |
par; | U+02225 | ∥ |
para; | U+000B6 | ¶ |
para | U+000B6 | ¶ |
parallel; | U+02225 | ∥ |
parsim; | U+02AF3 | ⫳ |
parsl; | U+02AFD | ⫽ |
part; | U+02202 | ∂ |
PartialD; | U+02202 | ∂ |
Pcy; | U+0041F | П |
pcy; | U+0043F | п |
percnt; | U+00025 | % |
period; | U+0002E | . |
permil; | U+02030 | ‰ |
perp; | U+022A5 | ⊥ |
pertenk; | U+02031 | ‱ |
Pfr; | U+1D513 | 𝔓 |
pfr; | U+1D52D | 𝔭 |
Phi; | U+003A6 | Φ |
phi; | U+003C6 | φ |
phiv; | U+003D5 | ϕ |
phmmat; | U+02133 | ℳ |
phone; | U+0260E | ☎ |
Pi; | U+003A0 | Π |
pi; | U+003C0 | π |
pitchfork; | U+022D4 | ⋔ |
piv; | U+003D6 | ϖ |
planck; | U+0210F | ℏ |
planckh; | U+0210E | ℎ |
plankv; | U+0210F | ℏ |
plus; | U+0002B | + |
plusacir; | U+02A23 | ⨣ |
plusb; | U+0229E | ⊞ |
pluscir; | U+02A22 | ⨢ |
plusdo; | U+02214 | ∔ |
plusdu; | U+02A25 | ⨥ |
pluse; | U+02A72 | ⩲ |
PlusMinus; | U+000B1 | ± |
plusmn; | U+000B1 | ± |
plusmn | U+000B1 | ± |
plussim; | U+02A26 | ⨦ |
plustwo; | U+02A27 | ⨧ |
pm; | U+000B1 | ± |
Poincareplane; | U+0210C | ℌ |
pointint; | U+02A15 | ⨕ |
Popf; | U+02119 | ℙ |
popf; | U+1D561 | 𝕡 |
pound; | U+000A3 | £ |
pound | U+000A3 | £ |
Pr; | U+02ABB | ⪻ |
pr; | U+0227A | ≺ |
prap; | U+02AB7 | ⪷ |
prcue; | U+0227C | ≼ |
prE; | U+02AB3 | ⪳ |
pre; | U+02AAF | ⪯ |
prec; | U+0227A | ≺ |
precapprox; | U+02AB7 | ⪷ |
preccurlyeq; | U+0227C | ≼ |
Precedes; | U+0227A | ≺ |
PrecedesEqual; | U+02AAF | ⪯ |
PrecedesSlantEqual; | U+0227C | ≼ |
PrecedesTilde; | U+0227E | ≾ |
preceq; | U+02AAF | ⪯ |
precnapprox; | U+02AB9 | ⪹ |
precneqq; | U+02AB5 | ⪵ |
precnsim; | U+022E8 | ⋨ |
precsim; | U+0227E | ≾ |
Prime; | U+02033 | ″ |
prime; | U+02032 | ′ |
primes; | U+02119 | ℙ |
prnap; | U+02AB9 | ⪹ |
prnE; | U+02AB5 | ⪵ |
prnsim; | U+022E8 | ⋨ |
prod; | U+0220F | ∏ |
Product; | U+0220F | ∏ |
profalar; | U+0232E | ⌮ |
profline; | U+02312 | ⌒ |
profsurf; | U+02313 | ⌓ |
prop; | U+0221D | ∝ |
Proportion; | U+02237 | ∷ |
Proportional; | U+0221D | ∝ |
propto; | U+0221D | ∝ |
prsim; | U+0227E | ≾ |
prurel; | U+022B0 | ⊰ |
Pscr; | U+1D4AB | 𝒫 |
pscr; | U+1D4C5 | 𝓅 |
Psi; | U+003A8 | Ψ |
psi; | U+003C8 | ψ |
puncsp; | U+02008 | |
Qfr; | U+1D514 | 𝔔 |
qfr; | U+1D52E | 𝔮 |
qint; | U+02A0C | ⨌ |
Qopf; | U+0211A | ℚ |
qopf; | U+1D562 | 𝕢 |
qprime; | U+02057 | ⁗ |
Qscr; | U+1D4AC | 𝒬 |
qscr; | U+1D4C6 | 𝓆 |
quaternions; | U+0210D | ℍ |
quatint; | U+02A16 | ⨖ |
quest; | U+0003F | ? |
questeq; | U+0225F | ≟ |
QUOT; | U+00022 | " |
QUOT | U+00022 | " |
quot; | U+00022 | " |
quot | U+00022 | " |
rAarr; | U+021DB | ⇛ |
race; | U+0223D U+00331 | ∽̱ |
Racute; | U+00154 | Ŕ |
racute; | U+00155 | ŕ |
radic; | U+0221A | √ |
raemptyv; | U+029B3 | ⦳ |
Rang; | U+027EB | ⟫ |
rang; | U+027E9 | ⟩ |
rangd; | U+02992 | ⦒ |
range; | U+029A5 | ⦥ |
rangle; | U+027E9 | ⟩ |
raquo; | U+000BB | » |
raquo | U+000BB | » |
Rarr; | U+021A0 | ↠ |
rArr; | U+021D2 | ⇒ |
rarr; | U+02192 | → |
rarrap; | U+02975 | ⥵ |
rarrb; | U+021E5 | ⇥ |
rarrbfs; | U+02920 | ⤠ |
rarrc; | U+02933 | ⤳ |
rarrfs; | U+0291E | ⤞ |
rarrhk; | U+021AA | ↪ |
rarrlp; | U+021AC | ↬ |
rarrpl; | U+02945 | ⥅ |
rarrsim; | U+02974 | ⥴ |
Rarrtl; | U+02916 | ⤖ |
rarrtl; | U+021A3 | ↣ |
rarrw; | U+0219D | ↝ |
rAtail; | U+0291C | ⤜ |
ratail; | U+0291A | ⤚ |
ratio; | U+02236 | ∶ |
rationals; | U+0211A | ℚ |
RBarr; | U+02910 | ⤐ |
rBarr; | U+0290F | ⤏ |
rbarr; | U+0290D | ⤍ |
rbbrk; | U+02773 | ❳ |
rbrace; | U+0007D | } |
rbrack; | U+0005D | ] |
rbrke; | U+0298C | ⦌ |
rbrksld; | U+0298E | ⦎ |
rbrkslu; | U+02990 | ⦐ |
Rcaron; | U+00158 | Ř |
rcaron; | U+00159 | ř |
Rcedil; | U+00156 | Ŗ |
rcedil; | U+00157 | ŗ |
rceil; | U+02309 | ⌉ |
rcub; | U+0007D | } |
Rcy; | U+00420 | Р |
rcy; | U+00440 | р |
rdca; | U+02937 | ⤷ |
rdldhar; | U+02969 | ⥩ |
rdquo; | U+0201D | ” |
rdquor; | U+0201D | ” |
rdsh; | U+021B3 | ↳ |
Re; | U+0211C | ℜ |
real; | U+0211C | ℜ |
realine; | U+0211B | ℛ |
realpart; | U+0211C | ℜ |
reals; | U+0211D | ℝ |
rect; | U+025AD | ▭ |
REG; | U+000AE | ® |
REG | U+000AE | ® |
reg; | U+000AE | ® |
reg | U+000AE | ® |
ReverseElement; | U+0220B | ∋ |
ReverseEquilibrium; | U+021CB | ⇋ |
ReverseUpEquilibrium; | U+0296F | ⥯ |
rfisht; | U+0297D | ⥽ |
rfloor; | U+0230B | ⌋ |
Rfr; | U+0211C | ℜ |
rfr; | U+1D52F | 𝔯 |
rHar; | U+02964 | ⥤ |
rhard; | U+021C1 | ⇁ |
rharu; | U+021C0 | ⇀ |
rharul; | U+0296C | ⥬ |
Rho; | U+003A1 | Ρ |
rho; | U+003C1 | ρ |
rhov; | U+003F1 | ϱ |
RightAngleBracket; | U+027E9 | ⟩ |
RightArrow; | U+02192 | → |
Rightarrow; | U+021D2 | ⇒ |
rightarrow; | U+02192 | → |
RightArrowBar; | U+021E5 | ⇥ |
RightArrowLeftArrow; | U+021C4 | ⇄ |
rightarrowtail; | U+021A3 | ↣ |
RightCeiling; | U+02309 | ⌉ |
RightDoubleBracket; | U+027E7 | ⟧ |
RightDownTeeVector; | U+0295D | ⥝ |
RightDownVector; | U+021C2 | ⇂ |
RightDownVectorBar; | U+02955 | ⥕ |
RightFloor; | U+0230B | ⌋ |
rightharpoondown; | U+021C1 | ⇁ |
rightharpoonup; | U+021C0 | ⇀ |
rightleftarrows; | U+021C4 | ⇄ |
rightleftharpoons; | U+021CC | ⇌ |
rightrightarrows; | U+021C9 | ⇉ |
rightsquigarrow; | U+0219D | ↝ |
RightTee; | U+022A2 | ⊢ |
RightTeeArrow; | U+021A6 | ↦ |
RightTeeVector; | U+0295B | ⥛ |
rightthreetimes; | U+022CC | ⋌ |
RightTriangle; | U+022B3 | ⊳ |
RightTriangleBar; | U+029D0 | ⧐ |
RightTriangleEqual; | U+022B5 | ⊵ |
RightUpDownVector; | U+0294F | ⥏ |
RightUpTeeVector; | U+0295C | ⥜ |
RightUpVector; | U+021BE | ↾ |
RightUpVectorBar; | U+02954 | ⥔ |
RightVector; | U+021C0 | ⇀ |
RightVectorBar; | U+02953 | ⥓ |
ring; | U+002DA | ˚ |
risingdotseq; | U+02253 | ≓ |
rlarr; | U+021C4 | ⇄ |
rlhar; | U+021CC | ⇌ |
rlm; | U+0200F | |
rmoust; | U+023B1 | ⎱ |
rmoustache; | U+023B1 | ⎱ |
rnmid; | U+02AEE | ⫮ |
roang; | U+027ED | ⟭ |
roarr; | U+021FE | ⇾ |
robrk; | U+027E7 | ⟧ |
ropar; | U+02986 | ⦆ |
Ropf; | U+0211D | ℝ |
ropf; | U+1D563 | 𝕣 |
roplus; | U+02A2E | ⨮ |
rotimes; | U+02A35 | ⨵ |
RoundImplies; | U+02970 | ⥰ |
rpar; | U+00029 | ) |
rpargt; | U+02994 | ⦔ |
rppolint; | U+02A12 | ⨒ |
rrarr; | U+021C9 | ⇉ |
Rrightarrow; | U+021DB | ⇛ |
rsaquo; | U+0203A | › |
Rscr; | U+0211B | ℛ |
rscr; | U+1D4C7 | 𝓇 |
Rsh; | U+021B1 | ↱ |
rsh; | U+021B1 | ↱ |
rsqb; | U+0005D | ] |
rsquo; | U+02019 | ’ |
rsquor; | U+02019 | ’ |
rthree; | U+022CC | ⋌ |
rtimes; | U+022CA | ⋊ |
rtri; | U+025B9 | ▹ |
rtrie; | U+022B5 | ⊵ |
rtrif; | U+025B8 | ▸ |
rtriltri; | U+029CE | ⧎ |
RuleDelayed; | U+029F4 | ⧴ |
ruluhar; | U+02968 | ⥨ |
rx; | U+0211E | ℞ |
Sacute; | U+0015A | Ś |
sacute; | U+0015B | ś |
sbquo; | U+0201A | ‚ |
Sc; | U+02ABC | ⪼ |
sc; | U+0227B | ≻ |
scap; | U+02AB8 | ⪸ |
Scaron; | U+00160 | Š |
scaron; | U+00161 | š |
sccue; | U+0227D | ≽ |
scE; | U+02AB4 | ⪴ |
sce; | U+02AB0 | ⪰ |
Scedil; | U+0015E | Ş |
scedil; | U+0015F | ş |
Scirc; | U+0015C | Ŝ |
scirc; | U+0015D | ŝ |
scnap; | U+02ABA | ⪺ |
scnE; | U+02AB6 | ⪶ |
scnsim; | U+022E9 | ⋩ |
scpolint; | U+02A13 | ⨓ |
scsim; | U+0227F | ≿ |
Scy; | U+00421 | С |
scy; | U+00441 | с |
sdot; | U+022C5 | ⋅ |
sdotb; | U+022A1 | ⊡ |
sdote; | U+02A66 | ⩦ |
searhk; | U+02925 | ⤥ |
seArr; | U+021D8 | ⇘ |
searr; | U+02198 | ↘ |
searrow; | U+02198 | ↘ |
sect; | U+000A7 | § |
sect | U+000A7 | § |
semi; | U+0003B | ; |
seswar; | U+02929 | ⤩ |
setminus; | U+02216 | ∖ |
setmn; | U+02216 | ∖ |
sext; | U+02736 | ✶ |
Sfr; | U+1D516 | 𝔖 |
sfr; | U+1D530 | 𝔰 |
sfrown; | U+02322 | ⌢ |
sharp; | U+0266F | ♯ |
SHCHcy; | U+00429 | Щ |
shchcy; | U+00449 | щ |
SHcy; | U+00428 | Ш |
shcy; | U+00448 | ш |
ShortDownArrow; | U+02193 | ↓ |
ShortLeftArrow; | U+02190 | ← |
shortmid; | U+02223 | ∣ |
shortparallel; | U+02225 | ∥ |
ShortRightArrow; | U+02192 | → |
ShortUpArrow; | U+02191 | ↑ |
shy; | U+000AD | |
shy | U+000AD | |
Sigma; | U+003A3 | Σ |
sigma; | U+003C3 | σ |
sigmaf; | U+003C2 | ς |
sigmav; | U+003C2 | ς |
sim; | U+0223C | ∼ |
simdot; | U+02A6A | ⩪ |
sime; | U+02243 | ≃ |
simeq; | U+02243 | ≃ |
simg; | U+02A9E | ⪞ |
simgE; | U+02AA0 | ⪠ |
siml; | U+02A9D | ⪝ |
simlE; | U+02A9F | ⪟ |
simne; | U+02246 | ≆ |
simplus; | U+02A24 | ⨤ |
simrarr; | U+02972 | ⥲ |
slarr; | U+02190 | ← |
SmallCircle; | U+02218 | ∘ |
smallsetminus; | U+02216 | ∖ |
smashp; | U+02A33 | ⨳ |
smeparsl; | U+029E4 | ⧤ |
smid; | U+02223 | ∣ |
smile; | U+02323 | ⌣ |
smt; | U+02AAA | ⪪ |
smte; | U+02AAC | ⪬ |
smtes; | U+02AAC U+0FE00 | ⪬︀ |
SOFTcy; | U+0042C | Ь |
softcy; | U+0044C | ь |
sol; | U+0002F | / |
solb; | U+029C4 | ⧄ |
solbar; | U+0233F | ⌿ |
Sopf; | U+1D54A | 𝕊 |
sopf; | U+1D564 | 𝕤 |
spades; | U+02660 | ♠ |
spadesuit; | U+02660 | ♠ |
spar; | U+02225 | ∥ |
sqcap; | U+02293 | ⊓ |
sqcaps; | U+02293 U+0FE00 | ⊓︀ |
sqcup; | U+02294 | ⊔ |
sqcups; | U+02294 U+0FE00 | ⊔︀ |
Sqrt; | U+0221A | √ |
sqsub; | U+0228F | ⊏ |
sqsube; | U+02291 | ⊑ |
sqsubset; | U+0228F | ⊏ |
sqsubseteq; | U+02291 | ⊑ |
sqsup; | U+02290 | ⊐ |
sqsupe; | U+02292 | ⊒ |
sqsupset; | U+02290 | ⊐ |
sqsupseteq; | U+02292 | ⊒ |
squ; | U+025A1 | □ |
Square; | U+025A1 | □ |
square; | U+025A1 | □ |
SquareIntersection; | U+02293 | ⊓ |
SquareSubset; | U+0228F | ⊏ |
SquareSubsetEqual; | U+02291 | ⊑ |
SquareSuperset; | U+02290 | ⊐ |
SquareSupersetEqual; | U+02292 | ⊒ |
SquareUnion; | U+02294 | ⊔ |
squarf; | U+025AA | ▪ |
squf; | U+025AA | ▪ |
srarr; | U+02192 | → |
Sscr; | U+1D4AE | 𝒮 |
sscr; | U+1D4C8 | 𝓈 |
ssetmn; | U+02216 | ∖ |
ssmile; | U+02323 | ⌣ |
sstarf; | U+022C6 | ⋆ |
Star; | U+022C6 | ⋆ |
star; | U+02606 | ☆ |
starf; | U+02605 | ★ |
straightepsilon; | U+003F5 | ϵ |
straightphi; | U+003D5 | ϕ |
strns; | U+000AF | ¯ |
Sub; | U+022D0 | ⋐ |
sub; | U+02282 | ⊂ |
subdot; | U+02ABD | ⪽ |
subE; | U+02AC5 | ⫅ |
sube; | U+02286 | ⊆ |
subedot; | U+02AC3 | ⫃ |
submult; | U+02AC1 | ⫁ |
subnE; | U+02ACB | ⫋ |
subne; | U+0228A | ⊊ |
subplus; | U+02ABF | ⪿ |
subrarr; | U+02979 | ⥹ |
Subset; | U+022D0 | ⋐ |
subset; | U+02282 | ⊂ |
subseteq; | U+02286 | ⊆ |
subseteqq; | U+02AC5 | ⫅ |
SubsetEqual; | U+02286 | ⊆ |
subsetneq; | U+0228A | ⊊ |
subsetneqq; | U+02ACB | ⫋ |
subsim; | U+02AC7 | ⫇ |
subsub; | U+02AD5 | ⫕ |
subsup; | U+02AD3 | ⫓ |
succ; | U+0227B | ≻ |
succapprox; | U+02AB8 | ⪸ |
succcurlyeq; | U+0227D | ≽ |
Succeeds; | U+0227B | ≻ |
SucceedsEqual; | U+02AB0 | ⪰ |
SucceedsSlantEqual; | U+0227D | ≽ |
SucceedsTilde; | U+0227F | ≿ |
succeq; | U+02AB0 | ⪰ |
succnapprox; | U+02ABA | ⪺ |
succneqq; | U+02AB6 | ⪶ |
succnsim; | U+022E9 | ⋩ |
succsim; | U+0227F | ≿ |
SuchThat; | U+0220B | ∋ |
Sum; | U+02211 | ∑ |
sum; | U+02211 | ∑ |
sung; | U+0266A | ♪ |
Sup; | U+022D1 | ⋑ |
sup; | U+02283 | ⊃ |
sup1; | U+000B9 | ¹ |
sup1 | U+000B9 | ¹ |
sup2; | U+000B2 | ² |
sup2 | U+000B2 | ² |
sup3; | U+000B3 | ³ |
sup3 | U+000B3 | ³ |
supdot; | U+02ABE | ⪾ |
supdsub; | U+02AD8 | ⫘ |
supE; | U+02AC6 | ⫆ |
supe; | U+02287 | ⊇ |
supedot; | U+02AC4 | ⫄ |
Superset; | U+02283 | ⊃ |
SupersetEqual; | U+02287 | ⊇ |
suphsol; | U+027C9 | ⟉ |
suphsub; | U+02AD7 | ⫗ |
suplarr; | U+0297B | ⥻ |
supmult; | U+02AC2 | ⫂ |
supnE; | U+02ACC | ⫌ |
supne; | U+0228B | ⊋ |
supplus; | U+02AC0 | ⫀ |
Supset; | U+022D1 | ⋑ |
supset; | U+02283 | ⊃ |
supseteq; | U+02287 | ⊇ |
supseteqq; | U+02AC6 | ⫆ |
supsetneq; | U+0228B | ⊋ |
supsetneqq; | U+02ACC | ⫌ |
supsim; | U+02AC8 | ⫈ |
supsub; | U+02AD4 | ⫔ |
supsup; | U+02AD6 | ⫖ |
swarhk; | U+02926 | ⤦ |
swArr; | U+021D9 | ⇙ |
swarr; | U+02199 | ↙ |
swarrow; | U+02199 | ↙ |
swnwar; | U+0292A | ⤪ |
szlig; | U+000DF | ß |
szlig | U+000DF | ß |
Tab; | U+00009 | ␉ |
target; | U+02316 | ⌖ |
Tau; | U+003A4 | Τ |
tau; | U+003C4 | τ |
tbrk; | U+023B4 | ⎴ |
Tcaron; | U+00164 | Ť |
tcaron; | U+00165 | ť |
Tcedil; | U+00162 | Ţ |
tcedil; | U+00163 | ţ |
Tcy; | U+00422 | Т |
tcy; | U+00442 | т |
tdot; | U+020DB | ◌⃛ |
telrec; | U+02315 | ⌕ |
Tfr; | U+1D517 | 𝔗 |
tfr; | U+1D531 | 𝔱 |
there4; | U+02234 | ∴ |
Therefore; | U+02234 | ∴ |
therefore; | U+02234 | ∴ |
Theta; | U+00398 | Θ |
theta; | U+003B8 | θ |
thetasym; | U+003D1 | ϑ |
thetav; | U+003D1 | ϑ |
thickapprox; | U+02248 | ≈ |
thicksim; | U+0223C | ∼ |
ThickSpace; | U+0205F U+0200A | |
thinsp; | U+02009 | |
ThinSpace; | U+02009 | |
thkap; | U+02248 | ≈ |
thksim; | U+0223C | ∼ |
THORN; | U+000DE | Þ |
THORN | U+000DE | Þ |
thorn; | U+000FE | þ |
thorn | U+000FE | þ |
Tilde; | U+0223C | ∼ |
tilde; | U+002DC | ˜ |
TildeEqual; | U+02243 | ≃ |
TildeFullEqual; | U+02245 | ≅ |
TildeTilde; | U+02248 | ≈ |
times; | U+000D7 | × |
times | U+000D7 | × |
timesb; | U+022A0 | ⊠ |
timesbar; | U+02A31 | ⨱ |
timesd; | U+02A30 | ⨰ |
tint; | U+0222D | ∭ |
toea; | U+02928 | ⤨ |
top; | U+022A4 | ⊤ |
topbot; | U+02336 | ⌶ |
topcir; | U+02AF1 | ⫱ |
Topf; | U+1D54B | 𝕋 |
topf; | U+1D565 | 𝕥 |
topfork; | U+02ADA | ⫚ |
tosa; | U+02929 | ⤩ |
tprime; | U+02034 | ‴ |
TRADE; | U+02122 | ™ |
trade; | U+02122 | ™ |
triangle; | U+025B5 | ▵ |
triangledown; | U+025BF | ▿ |
triangleleft; | U+025C3 | ◃ |
trianglelefteq; | U+022B4 | ⊴ |
triangleq; | U+0225C | ≜ |
triangleright; | U+025B9 | ▹ |
trianglerighteq; | U+022B5 | ⊵ |
tridot; | U+025EC | ◬ |
trie; | U+0225C | ≜ |
triminus; | U+02A3A | ⨺ |
TripleDot; | U+020DB | ◌⃛ |
triplus; | U+02A39 | ⨹ |
trisb; | U+029CD | ⧍ |
tritime; | U+02A3B | ⨻ |
trpezium; | U+023E2 | ⏢ |
Tscr; | U+1D4AF | 𝒯 |
tscr; | U+1D4C9 | 𝓉 |
TScy; | U+00426 | Ц |
tscy; | U+00446 | ц |
TSHcy; | U+0040B | Ћ |
tshcy; | U+0045B | ћ |
Tstrok; | U+00166 | Ŧ |
tstrok; | U+00167 | ŧ |
twixt; | U+0226C | ≬ |
twoheadleftarrow; | U+0219E | ↞ |
twoheadrightarrow; | U+021A0 | ↠ |
Uacute; | U+000DA | Ú |
Uacute | U+000DA | Ú |
uacute; | U+000FA | ú |
uacute | U+000FA | ú |
Uarr; | U+0219F | ↟ |
uArr; | U+021D1 | ⇑ |
uarr; | U+02191 | ↑ |
Uarrocir; | U+02949 | ⥉ |
Ubrcy; | U+0040E | Ў |
ubrcy; | U+0045E | ў |
Ubreve; | U+0016C | Ŭ |
ubreve; | U+0016D | ŭ |
Ucirc; | U+000DB | Û |
Ucirc | U+000DB | Û |
ucirc; | U+000FB | û |
ucirc | U+000FB | û |
Ucy; | U+00423 | У |
ucy; | U+00443 | у |
udarr; | U+021C5 | ⇅ |
Udblac; | U+00170 | Ű |
udblac; | U+00171 | ű |
udhar; | U+0296E | ⥮ |
ufisht; | U+0297E | ⥾ |
Ufr; | U+1D518 | 𝔘 |
ufr; | U+1D532 | 𝔲 |
Ugrave; | U+000D9 | Ù |
Ugrave | U+000D9 | Ù |
ugrave; | U+000F9 | ù |
ugrave | U+000F9 | ù |
uHar; | U+02963 | ⥣ |
uharl; | U+021BF | ↿ |
uharr; | U+021BE | ↾ |
uhblk; | U+02580 | ▀ |
ulcorn; | U+0231C | ⌜ |
ulcorner; | U+0231C | ⌜ |
ulcrop; | U+0230F | ⌏ |
ultri; | U+025F8 | ◸ |
Umacr; | U+0016A | Ū |
umacr; | U+0016B | ū |
uml; | U+000A8 | ¨ |
uml | U+000A8 | ¨ |
UnderBar; | U+0005F | _ |
UnderBrace; | U+023DF | ⏟ |
UnderBracket; | U+023B5 | ⎵ |
UnderParenthesis; | U+023DD | ⏝ |
Union; | U+022C3 | ⋃ |
UnionPlus; | U+0228E | ⊎ |
Uogon; | U+00172 | Ų |
uogon; | U+00173 | ų |
Uopf; | U+1D54C | 𝕌 |
uopf; | U+1D566 | 𝕦 |
UpArrow; | U+02191 | ↑ |
Uparrow; | U+021D1 | ⇑ |
uparrow; | U+02191 | ↑ |
UpArrowBar; | U+02912 | ⤒ |
UpArrowDownArrow; | U+021C5 | ⇅ |
UpDownArrow; | U+02195 | ↕ |
Updownarrow; | U+021D5 | ⇕ |
updownarrow; | U+02195 | ↕ |
UpEquilibrium; | U+0296E | ⥮ |
upharpoonleft; | U+021BF | ↿ |
upharpoonright; | U+021BE | ↾ |
uplus; | U+0228E | ⊎ |
UpperLeftArrow; | U+02196 | ↖ |
UpperRightArrow; | U+02197 | ↗ |
Upsi; | U+003D2 | ϒ |
upsi; | U+003C5 | υ |
upsih; | U+003D2 | ϒ |
Upsilon; | U+003A5 | Υ |
upsilon; | U+003C5 | υ |
UpTee; | U+022A5 | ⊥ |
UpTeeArrow; | U+021A5 | ↥ |
upuparrows; | U+021C8 | ⇈ |
urcorn; | U+0231D | ⌝ |
urcorner; | U+0231D | ⌝ |
urcrop; | U+0230E | ⌎ |
Uring; | U+0016E | Ů |
uring; | U+0016F | ů |
urtri; | U+025F9 | ◹ |
Uscr; | U+1D4B0 | 𝒰 |
uscr; | U+1D4CA | 𝓊 |
utdot; | U+022F0 | ⋰ |
Utilde; | U+00168 | Ũ |
utilde; | U+00169 | ũ |
utri; | U+025B5 | ▵ |
utrif; | U+025B4 | ▴ |
uuarr; | U+021C8 | ⇈ |
Uuml; | U+000DC | Ü |
Uuml | U+000DC | Ü |
uuml; | U+000FC | ü |
uuml | U+000FC | ü |
uwangle; | U+029A7 | ⦧ |
vangrt; | U+0299C | ⦜ |
varepsilon; | U+003F5 | ϵ |
varkappa; | U+003F0 | ϰ |
varnothing; | U+02205 | ∅ |
varphi; | U+003D5 | ϕ |
varpi; | U+003D6 | ϖ |
varpropto; | U+0221D | ∝ |
vArr; | U+021D5 | ⇕ |
varr; | U+02195 | ↕ |
varrho; | U+003F1 | ϱ |
varsigma; | U+003C2 | ς |
varsubsetneq; | U+0228A U+0FE00 | ⊊︀ |
varsubsetneqq; | U+02ACB U+0FE00 | ⫋︀ |
varsupsetneq; | U+0228B U+0FE00 | ⊋︀ |
varsupsetneqq; | U+02ACC U+0FE00 | ⫌︀ |
vartheta; | U+003D1 | ϑ |
vartriangleleft; | U+022B2 | ⊲ |
vartriangleright; | U+022B3 | ⊳ |
Vbar; | U+02AEB | ⫫ |
vBar; | U+02AE8 | ⫨ |
vBarv; | U+02AE9 | ⫩ |
Vcy; | U+00412 | В |
vcy; | U+00432 | в |
VDash; | U+022AB | ⊫ |
Vdash; | U+022A9 | ⊩ |
vDash; | U+022A8 | ⊨ |
vdash; | U+022A2 | ⊢ |
Vdashl; | U+02AE6 | ⫦ |
Vee; | U+022C1 | ⋁ |
vee; | U+02228 | ∨ |
veebar; | U+022BB | ⊻ |
veeeq; | U+0225A | ≚ |
vellip; | U+022EE | ⋮ |
Verbar; | U+02016 | ‖ |
verbar; | U+0007C | | |
Vert; | U+02016 | ‖ |
vert; | U+0007C | | |
VerticalBar; | U+02223 | ∣ |
VerticalLine; | U+0007C | | |
VerticalSeparator; | U+02758 | ❘ |
VerticalTilde; | U+02240 | ≀ |
VeryThinSpace; | U+0200A | |
Vfr; | U+1D519 | 𝔙 |
vfr; | U+1D533 | 𝔳 |
vltri; | U+022B2 | ⊲ |
vnsub; | U+02282 U+020D2 | ⊂⃒ |
vnsup; | U+02283 U+020D2 | ⊃⃒ |
Vopf; | U+1D54D | 𝕍 |
vopf; | U+1D567 | 𝕧 |
vprop; | U+0221D | ∝ |
vrtri; | U+022B3 | ⊳ |
Vscr; | U+1D4B1 | 𝒱 |
vscr; | U+1D4CB | 𝓋 |
vsubnE; | U+02ACB U+0FE00 | ⫋︀ |
vsubne; | U+0228A U+0FE00 | ⊊︀ |
vsupnE; | U+02ACC U+0FE00 | ⫌︀ |
vsupne; | U+0228B U+0FE00 | ⊋︀ |
Vvdash; | U+022AA | ⊪ |
vzigzag; | U+0299A | ⦚ |
Wcirc; | U+00174 | Ŵ |
wcirc; | U+00175 | ŵ |
wedbar; | U+02A5F | ⩟ |
Wedge; | U+022C0 | ⋀ |
wedge; | U+02227 | ∧ |
wedgeq; | U+02259 | ≙ |
weierp; | U+02118 | ℘ |
Wfr; | U+1D51A | 𝔚 |
wfr; | U+1D534 | 𝔴 |
Wopf; | U+1D54E | 𝕎 |
wopf; | U+1D568 | 𝕨 |
wp; | U+02118 | ℘ |
wr; | U+02240 | ≀ |
wreath; | U+02240 | ≀ |
Wscr; | U+1D4B2 | 𝒲 |
wscr; | U+1D4CC | 𝓌 |
xcap; | U+022C2 | ⋂ |
xcirc; | U+025EF | ◯ |
xcup; | U+022C3 | ⋃ |
xdtri; | U+025BD | ▽ |
Xfr; | U+1D51B | 𝔛 |
xfr; | U+1D535 | 𝔵 |
xhArr; | U+027FA | ⟺ |
xharr; | U+027F7 | ⟷ |
Xi; | U+0039E | Ξ |
xi; | U+003BE | ξ |
xlArr; | U+027F8 | ⟸ |
xlarr; | U+027F5 | ⟵ |
xmap; | U+027FC | ⟼ |
xnis; | U+022FB | ⋻ |
xodot; | U+02A00 | ⨀ |
Xopf; | U+1D54F | 𝕏 |
xopf; | U+1D569 | 𝕩 |
xoplus; | U+02A01 | ⨁ |
xotime; | U+02A02 | ⨂ |
xrArr; | U+027F9 | ⟹ |
xrarr; | U+027F6 | ⟶ |
Xscr; | U+1D4B3 | 𝒳 |
xscr; | U+1D4CD | 𝓍 |
xsqcup; | U+02A06 | ⨆ |
xuplus; | U+02A04 | ⨄ |
xutri; | U+025B3 | △ |
xvee; | U+022C1 | ⋁ |
xwedge; | U+022C0 | ⋀ |
Yacute; | U+000DD | Ý |
Yacute | U+000DD | Ý |
yacute; | U+000FD | ý |
yacute | U+000FD | ý |
YAcy; | U+0042F | Я |
yacy; | U+0044F | я |
Ycirc; | U+00176 | Ŷ |
ycirc; | U+00177 | ŷ |
Ycy; | U+0042B | Ы |
ycy; | U+0044B | ы |
yen; | U+000A5 | ¥ |
yen | U+000A5 | ¥ |
Yfr; | U+1D51C | 𝔜 |
yfr; | U+1D536 | 𝔶 |
YIcy; | U+00407 | Ї |
yicy; | U+00457 | ї |
Yopf; | U+1D550 | 𝕐 |
yopf; | U+1D56A | 𝕪 |
Yscr; | U+1D4B4 | 𝒴 |
yscr; | U+1D4CE | 𝓎 |
YUcy; | U+0042E | Ю |
yucy; | U+0044E | ю |
Yuml; | U+00178 | Ÿ |
yuml; | U+000FF | ÿ |
yuml | U+000FF | ÿ |
Zacute; | U+00179 | Ź |
zacute; | U+0017A | ź |
Zcaron; | U+0017D | Ž |
zcaron; | U+0017E | ž |
Zcy; | U+00417 | З |
zcy; | U+00437 | з |
Zdot; | U+0017B | Ż |
zdot; | U+0017C | ż |
zeetrf; | U+02128 | ℨ |
ZeroWidthSpace; | U+0200B | |
Zeta; | U+00396 | Ζ |
zeta; | U+003B6 | ζ |
Zfr; | U+02128 | ℨ |
zfr; | U+1D537 | 𝔷 |
ZHcy; | U+00416 | Ж |
zhcy; | U+00436 | ж |
zigrarr; | U+021DD | ⇝ |
Zopf; | U+02124 | ℤ |
zopf; | U+1D56B | 𝕫 |
Zscr; | U+1D4B5 | 𝒵 |
zscr; | U+1D4CF | 𝓏 |
zwj; | U+0200D | |
zwnj; | U+0200C | |
This data is also available as a JSON file.
The glyphs displayed above are non-normative. Refer to Unicode for formal definitions of the characters listed above.
Support in all current engines.
The syntax for XML is defined in XML and Namespaces in XML. [XML] [XMLNS]
This specification does not define any syntax-level requirements beyond those defined for XML proper.
XML documents may contain a DOCTYPE if desired, but this is not required
to conform to this specification. This specification does not define a public or system
identifier, nor provide a formal DTD.
This section describes the relationship between XML and the DOM, with a particular emphasis on how this interacts with HTML.
An XML parser is either associated with a Document object when it is
created, or creates one implicitly.
This Document must then be populated with DOM nodes that represent the tree
structure of the input passed to the parser, as defined by XML, Namespaces
in XML, and DOM. When creating DOM nodes representing elements,
the create an element for a token algorithm
or some equivalent that operates on appropriate XML data structures must be used, to ensure the
proper element interfaces are created and that custom elements are set up correctly.
For the operations that the XML parser performs on the Document's
tree, the user agent must act as if elements and attributes were individually appended and set
respectively so as to trigger rules in this specification regarding what happens when an element
is inserted into a document or has its attributes set, and DOM's requirements
regarding mutation observers mean that mutation observers are fired.
[XML] [XMLNS] [DOM] [UIEVENTS]
Between the time an element's start tag is parsed and the time either the element's end tag is parsed or the parser detects a well-formedness error, the user agent must act as if the element was in a stack of open elements.
This specification provides the following additional information that user agents should use when retrieving an external entity: the public identifiers given in the following list all correspond to the URL given by this link. (This URL is a DTD containing the entity declarations for the names listed in the named character references section.) [XML]
-//W3C//DTD XHTML 1.0 Transitional//EN-//W3C//DTD XHTML 1.1//EN-//W3C//DTD XHTML 1.0 Strict//EN-//W3C//DTD XHTML 1.0 Frameset//EN-//W3C//DTD XHTML Basic 1.0//EN-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN-//W3C//DTD MathML 2.0//EN-//WAPFORUM//DTD XHTML Mobile 1.0//ENFurthermore, user agents should attempt to retrieve the above external entity's content when one of the above public identifiers is used, and should not attempt to retrieve any other external entity's content.
XML parsers can be invoked with XML scripting support enabled or XML scripting support disabled. Except where otherwise specified, XML parsers are invoked with XML scripting support enabled.
When an XML parser with XML scripting support
enabled creates a script element, it must have its parser
document set and its force async set to false. If
the parser was created as part of the XML fragment parsing algorithm, then the
element's already started must be set to true. When the element's end tag is
subsequently parsed, the user agent must perform a microtask checkpoint, and then
prepare the script element. If this
causes there to be a pending parsing-blocking script, then the user agent must run
the following steps:
Block this instance of the XML parser, such that the event loop will not run tasks that invoke it.
Spin the event loop until the parser's Document has no
style sheet that is blocking scripts and the pending parsing-blocking
script's ready to be parser-executed is true.
Unblock this instance of the XML parser, such that tasks that invoke it can again be run.
Execute the script element given by the pending parsing-blocking script.
Set the pending parsing-blocking script to null.
When an XML parser would append a node to a
template element, it must instead append it to the template element's
template contents (a DocumentFragment node).
When an XML parser creates a Node object, its node document
must be set to the node document of
the node into which the newly created node is to be inserted.
When an XML parser reaches the end of its input, it must stop parsing, following the same rules as the HTML parser. An XML parser can also be aborted, which must again be done in the same way as for an HTML parser.
For the purposes of conformance checkers, if a resource is determined to be in the XML syntax, then it is an XML document.
For Documents, the algorithm must return a string in the form of a document entity, if none of the error cases
below apply.
For Elements, the algorithm must return a string in the form of an internal general parsed entity, if none of the
error cases below apply.
In both cases, the string returned must be XML namespace-well-formed and must be an isomorphic
serialization of all of that node's relevant child nodes, in tree order.
User agents may adjust prefixes and namespace declarations in the serialization (and indeed might
be forced to do so in some cases to obtain namespace-well-formed XML). User agents may use a
combination of regular text and character references to represent Text nodes in the
DOM.
For Elements, if any of the elements in the serialization are in no namespace, the
default namespace in scope for those elements must be explicitly declared as the empty string. (This doesn't apply in the Document case.) [XML]
[XMLNS]
For the purposes of this section, an internal general parsed entity is considered XML namespace-well-formed if a document consisting of an element with no namespace declarations whose contents are the internal general parsed entity would itself be XML namespace-well-formed.
If any of the following error cases are found in the DOM subtree being serialized, then the
algorithm must throw an "InvalidStateError" DOMException
instead of returning a string:
Document node with no child element nodes.DocumentType node that has an external subset public identifier that contains
characters that are not matched by the XML PubidChar production. [XML]DocumentType node that has an external subset system identifier that contains
both a U+0022 QUOTATION MARK (") and a U+0027 APOSTROPHE (') or that contains characters that are
not matched by the XML Char production. [XML]Name production. [XML]Attr node with no namespace whose local name is the lowercase string "xmlns". [XMLNS]Element node with two or more attributes with the same local name and
namespace.Attr node, Text node, Comment node, or
ProcessingInstruction node whose data contains characters that are not matched by
the XML Char production. [XML]Comment node whose data contains two adjacent U+002D HYPHEN-MINUS characters
(-) or ends with such a character.ProcessingInstruction node whose target name is an ASCII
case-insensitive match for the string "xml".ProcessingInstruction node whose target name contains a U+003A COLON (:).ProcessingInstruction node whose data contains the string "?>".User agents are not required to present HTML documents in any particular way. However, this section provides a set of suggestions for rendering HTML documents that, if followed, are likely to lead to a user experience that closely resembles the experience intended by the documents' authors. So as to avoid confusion regarding the normativity of this section, "must" has not been used. Instead, the term "expected" is used to indicate behavior that will lead to this experience. For the purposes of conformance for user agents designated as supporting the suggested default rendering, the term "expected" in this section has the same conformance implications as "must".
The suggestions in this section are generally expressed in CSS terms. User agents are expected to either support CSS, or translate from the CSS rules given in this section to approximations for other presentation mechanisms.
In the absence of style-layer rules to the contrary (e.g. author style sheets), user agents are expected to render an element so that it conveys to the user the meaning that the element represents, as described by this specification.
The suggestions in this section generally assume a visual output medium with a resolution of 96dpi or greater, but HTML is intended to apply to multiple media (it is a media-independent language). User agent implementers are encouraged to adapt the suggestions in this section to their target media.
An element is delegating its rendering to its children if it is not being rendered but its children (if any) could be rendered, as a result of CSS 'display: contents', or some equivalent in other styling languages. [CSSDISPLAY]
User agents that do not honor author-level CSS style sheets are nonetheless expected to act as if they applied the CSS rules given in these sections in a manner consistent with this specification and the relevant CSS and Unicode specifications. [CSS] [UNICODE] [BIDI]
The CSS rules given in these subsections are, except where otherwise specified, expected to be used as part of the user-agent level style sheet defaults for all documents that contain HTML elements.
Some rules are intended for the author-level zero-specificity presentational hints part of the CSS cascade; these are explicitly called out as presentational hints.
When a user agent is to align descendants of a node, the user agent is expected to
align only those descendants that have both their 'margin-inline-start' and
'margin-inline-end' properties computing to a value other than 'auto', that are
over-constrained and that have one of those two margins with a used value forced to a
greater value, and that do not themselves have an applicable align
attribute. When multiple elements are to align a
particular descendant, the most deeply nested such element is expected to override the others.
Aligned elements are expected to be aligned by having the used
values of their margins on the line-left and line-right sides be
set accordingly. [CSSLOGICAL] [CSSWM]
@namespace "http://www.w3.org/1999/xhtml" ;
area, base, basefont, datalist, head, link, meta, noembed,
noframes, param, rp, script, style, template, title {
display : none;
}
{
display : none;
}
[hidden=until-found i]:not(embed) {
content-visibility : hidden;
}
embed[hidden] { display : inline; height : 0 ; width : 0 ; }
input[type=hidden i] { display : none !important; }
@media (scripting) {
noscript { display: none !important; }
}
@namespace "http://www.w3.org/1999/xhtml" ;
html, body { display : block; }
For each property in the table below, given a body element, the first attribute
that exists maps to the pixel length property on the body element. If
none of the attributes for a property are found, or if the value of the attribute that was found
cannot be parsed successfully, then a default value of 8px is expected to be used for that
property instead.
| Property | Source |
|---|---|
| 'margin-top' | The body element's marginheight attribute
|
The body element's topmargin attribute
| |
The body element's container frame element's marginheight attribute
| |
| 'margin-right' | The body element's marginwidth attribute
|
The body element's rightmargin attribute
| |
The body element's container frame element's marginwidth attribute
| |
| 'margin-bottom' | The body element's marginheight attribute
|
The body element's bottommargin attribute
| |
The body element's container frame element's marginheight attribute
| |
| 'margin-left' | The body element's marginwidth attribute
|
The body element's leftmargin attribute
| |
The body element's container frame element's marginwidth attribute
|
If the body element's node document's node navigable is
a child navigable, and the container of that
navigable is a frame or iframe element, then the
container frame element of the body element is that frame or
iframe element. Otherwise, there is no container frame element.
If a Document's node navigable is a child navigable,
then it is expected to be positioned and sized to fit inside the content box of the
container of that navigable. If the container is not being rendered, the
navigable is expected to have a viewport with zero width and zero
height.
If a Document's node navigable is a child navigable,
the container of that navigable is a
frame or iframe element, that element has a scrolling attribute, and that attribute's value is an ASCII
case-insensitive match for the string "off", "noscroll", or "no", then the user agent is expected to
prevent any scrollbars from being shown for the viewport of the
Document's node navigable, regardless of the 'overflow'
property that applies to that viewport.
When a body element has a background
attribute set to a non-empty value, the new value is expected to be encoding-parsed-and-serialized relative to
the element's node document, and if that does not return failure, the user agent is
expected to treat the attribute as a presentational
hint setting the element's 'background-image' property to the return
value.
When a body element has a bgcolor
attribute set, the new value is expected to be parsed using the rules for parsing a legacy
color value, and if that does not return failure, the user agent is expected to treat the
attribute as a presentational hint setting the
element's 'background-color' property to the resulting color.
When a body element has a text attribute, its
value is expected to be parsed using the rules for parsing a legacy color value, and
if that does not return failure, the user agent is expected to treat the attribute as a presentational hint setting the element's
'color' property to the resulting color.
When a body element has a link attribute, its
value is expected to be parsed using the rules for parsing a legacy color value, and
if that does not return failure, the user agent is expected to treat the attribute as a presentational hint setting the 'color' property
of any element in the Document matching the :link
pseudo-class to the resulting color.
When a body element has a vlink attribute,
its value is expected to be parsed using the rules for parsing a legacy color value,
and if that does not return failure, the user agent is expected to treat the attribute as a presentational hint setting the 'color' property
of any element in the Document matching the :visited pseudo-class to the resulting color.
When a body element has an alink attribute,
its value is expected to be parsed using the rules for parsing a legacy color value,
and if that does not return failure, the user agent is expected to treat the attribute as a presentational hint setting the 'color' property
of any element in the Document matching the
:active pseudo-class and either the :link pseudo-class or the :visited pseudo-class to the resulting color.
@namespace "http://www.w3.org/1999/xhtml" ;
address, blockquote, center, dialog, div, figure, figcaption, footer, form,
header, hr, legend, listing, main, p, plaintext, pre, search, xmp {
display : block;
}
blockquote, figure, listing, p, plaintext, pre, xmp {
margin-block : 1 em ;
}
blockquote, figure { margin-inline : 40 px ; }
address { font-style : italic; }
listing, plaintext, pre, xmp {
font-family : monospace; white-space : pre;
}
dialog:not([open]) { display : none; }
dialog {
position : absolute;
inset-inline-start : 0 ; inset-inline-end : 0 ;
width : fit-content;
height : fit-content;
margin : auto;
border : solid;
padding : 1 em ;
background-color : Canvas;
color : CanvasText;
}
dialog:modal {
position : fixed;
overflow : auto;
inset-block : 0 ;
max-width : calc ( 100 % - 6 px - 2 em );
max-height : calc ( 100 % - 6 px - 2 em );
}
dialog::backdrop {
background : rgba ( 0 , 0 , 0 , 0.1 );
}
[popover]:not(:popover-open):not(dialog[open]) {
display : none;
}
dialog:popover-open {
display : block;
}
[popover] {
position : fixed;
inset : 0 ;
width : fit-content;
height : fit-content;
margin : auto;
border : solid;
padding : 0.25 em ;
overflow : auto;
color : CanvasText;
background-color : Canvas;
}
:popover-open::backdrop {
position : fixed;
inset : 0 ;
pointer-events : none !important;
background-color: transparent;
}
slot {
display: contents;
}
The following rules are also expected to apply, as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
pre[wrap] { white-space : pre-wrap; }
In quirks mode, the following rules are also expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
form { margin-block-end : 1 em ; }
The center element, and the div element when it has an align attribute whose value is an ASCII
case-insensitive match for either the string "center" or the string
"middle", are expected to center text within themselves, as if they had
their 'text-align' property set to 'center' in a presentational hint, and to align descendants to the center.
The div element, when it has an align
attribute whose value is an ASCII case-insensitive match for the string "left", is expected to left-align text within itself, as if it had its
'text-align' property set to 'left' in a presentational hint, and to align descendants to the left.
The div element, when it has an align
attribute whose value is an ASCII case-insensitive match for the string "right", is expected to right-align text within itself, as if it had its
'text-align' property set to 'right' in a presentational hint, and to align descendants to the right.
The div element, when it has an align
attribute whose value is an ASCII case-insensitive match for the string "justify", is expected to full-justify text within itself, as if it had its
'text-align' property set to 'justify' in a presentational hint, and to align descendants to the left.
@namespace "http://www.w3.org/1999/xhtml" ;
cite, dfn, em, i, var { font-style : italic; }
b, strong { font-weight : bolder; }
code, kbd, samp, tt { font-family : monospace; }
big { font-size : larger; }
small { font-size : smaller; }
sub { vertical-align : sub; }
sup { vertical-align : super; }
sub, sup { line-height : normal; font-size : smaller; }
ruby { display : ruby; }
rt { display : ruby-text; }
:link { color : #0000EE; }
:visited { color : #551A8B; }
:link:active, :visited:active { color : #FF0000; }
:link, :visited { text-decoration : underline; cursor : pointer; }
:focus-visible { outline : auto; }
mark { background : yellow; color : black; } /* this color is just a suggestion and can be changed based on implementation feedback */
abbr[title], acronym[title] { text-decoration : dotted underline; }
ins, u { text-decoration : underline; }
del, s, strike { text-decoration : line-through; }
q::before { content : open-quote; }
q::after { content : close-quote; }
br { display-outside : newline; } /* this also has bidi implications */
nobr { white-space : nowrap; }
wbr { display-outside : break-opportunity; } /* this also has bidi implications */
nobr wbr { white-space : normal; }
The following rules are also expected to apply, as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
br[clear=left i] { clear : left; }
br[clear=right i] { clear : right; }
br[clear=all i], br[clear=both i] { clear : both; }
For the purposes of the CSS ruby model, runs of children of ruby elements that are
not rt or rp elements are expected to be wrapped in anonymous boxes
whose 'display' property has the value 'ruby-base'. [CSSRUBY]
When a particular part of a ruby has more than one annotation, the annotations should be distributed on both sides of the base text so as to minimize the stacking of ruby annotations on one side.
User agents that do not support correct ruby rendering are expected to render parentheses
around the text of rt elements in the absence of rp elements.
User agents are expected to support the 'clear' property on inline elements (in
order to render br elements with clear
attributes) in the manner described in the non-normative note to this effect in CSS.
The initial value for the 'color' property is expected to be black. The initial value for the 'background-color' property is expected to be 'transparent'. The canvas's background is expected to be white.
When a font element has a color
attribute, its value is expected to be parsed using the rules for parsing a legacy color
value, and if that does not return failure, the user agent is expected to treat the
attribute as a presentational hint setting the
element's 'color' property to the resulting color.
When a font element has a face
attribute, the user agent is expected to treat the attribute as a presentational hint setting the element's 'font-family' property to the
attribute's value.
@namespace "http://www.w3.org/1999/xhtml" ;
[dir]:dir(ltr), bdi:dir(ltr), input[type=tel i]:dir(ltr) { direction : ltr; }
[dir]:dir(rtl), bdi:dir(rtl) { direction : rtl; }
address, blockquote, center, div, figure, figcaption, footer, form, header, hr,
legend, listing, main, p, plaintext, pre, summary, xmp, article, aside, h1, h2,
h3, h4, h5, h6, hgroup, nav, section, search, table, caption, colgroup, col,
thead, tbody, tfoot, tr, td, th, dir, dd, dl, dt, menu, ol, ul, li, bdi, output,
[dir=ltr i], [dir=rtl i], [dir=auto i] {
unicode-bidi : isolate;
}
bdo, bdo[dir] { unicode-bidi : isolate-override; }
input[dir=auto i]:is([type=search i], [type=tel i], [type=url i],
[type=email i]), textarea[dir=auto i], pre[dir=auto i] {
unicode-bidi : plaintext;
}
/* see prose for input elements whose type attribute is in the Text state */
/* the rules setting the 'content' property on br and wbr elements also has bidi implications */
When an input element's dir attribute is in the
auto state and its type
attribute is in the Text state, then the user agent is
expected to act as if it had a user-agent-level style sheet rule setting the
'unicode-bidi' property to 'plaintext'.
Input fields (i.e. textarea elements, and input elements when their
type attribute is in the Text, Search,
Telephone, URL,
or Email state) are expected to present an editing
user interface with a directionality that matches the element's 'direction'
property.
When the document's character encoding is ISO-8859-8, the following rules are additionally expected to apply, following those above: [ENCODING]
@namespace "http://www.w3.org/1999/xhtml" ;
address, blockquote, center, div, figure, figcaption, footer, form, header, hr,
legend, listing, main, p, plaintext, pre, summary, xmp, article, aside, h1, h2,
h3, h4, h5, h6, hgroup, nav, section, search, table, caption, colgroup, col,
thead, tbody, tfoot, tr, td, th, dir, dd, dl, dt, menu, ol, ul, li, [dir=ltr i],
[dir=rtl i], [dir=auto i], *|* {
unicode-bidi : bidi-override;
}
input:not([type=submit i]):not([type=reset i]):not([type=button i]),
textarea {
unicode-bidi : normal;
}
@namespace "http://www.w3.org/1999/xhtml" ;
article, aside, h1, h2, h3, h4, h5, h6, hgroup, nav, section {
display : block;
}
h1 { margin-block : 0.67 em ; font-size : 2.00 em ; font-weight : bold; }
h2 { margin-block : 0.83 em ; font-size : 1.50 em ; font-weight : bold; }
h3 { margin-block : 1.00 em ; font-size : 1.17 em ; font-weight : bold; }
h4 { margin-block : 1.33 em ; font-size : 1.00 em ; font-weight : bold; }
h5 { margin-block : 1.67 em ; font-size : 0.83 em ; font-weight : bold; }
h6 { margin-block : 2.33 em ; font-size : 0.67 em ; font-weight : bold; }
In the following CSS block, x is shorthand for the following selector:
:is(article, aside, nav, section)
@namespace "http://www.w3.org/1999/xhtml" ;
x h1 { margin-block : 0.83 em ; font-size : 1.50 em ; }
x x h1 { margin-block : 1.00 em ; font-size : 1.17 em ; }
x x x h1 { margin-block : 1.33 em ; font-size : 1.00 em ; }
x x x x h1 { margin-block : 1.67 em ; font-size : 0.83 em ; }
x x x x x h1 { margin-block : 2.33 em ; font-size : 0.67 em ; }
@namespace "http://www.w3.org/1999/xhtml" ;
dir, dd, dl, dt, menu, ol, ul { display : block; }
li { display : list-item; text-align : match-parent; }
dir, dl, menu, ol, ul { margin-block : 1 em ; }
:is(dir, dl, menu, ol, ul) :is(dir, dl, menu, ol, ul) {
margin-block : 0 ;
}
dd { margin-inline-start : 40 px ; }
dir, menu, ol, ul { padding-inline-start : 40 px ; }
ol, ul, menu { counter-reset : list-item; }
ol { list-style-type : decimal; }
dir, menu, ul {
list-style-type : disc;
}
:is(dir, menu, ol, ul) :is(dir, menu, ul) {
list-style-type : circle;
}
:is(dir, menu, ol, ul) :is(dir, menu, ol, ul) :is(dir, menu, ul) {
list-style-type : square;
}
The following rules are also expected to apply, as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
ol[type="1"], li[type="1"] { list-style-type : decimal; }
ol[type=a s], li[type=a s] { list-style-type : lower-alpha; }
ol[type=A s], li[type=A s] { list-style-type : upper-alpha; }
ol[type=i s], li[type=i s] { list-style-type : lower-roman; }
ol[type=I s], li[type=I s] { list-style-type : upper-roman; }
ul[type=none i], li[type=none i] { list-style-type : none; }
ul[type=disc i], li[type=disc i] { list-style-type : disc; }
ul[type=circle i], li[type=circle i] { list-style-type : circle; }
ul[type=square i], li[type=square i] { list-style-type : square; }
When rendering li elements, non-CSS user agents are expected to use the
ordinal value of the li element to render the counter in the list item
marker.
For CSS user agents, some aspects of rendering list items are defined by the CSS Lists specification. Additionally, the following attribute mappings are expected to apply: [CSSLISTS]
When an li element has a value attribute, and parsing that attribute's value using the
rules for parsing integers doesn't generate an error, the user agent is expected to
use the parsed value value as a presentational
hint for the 'counter-set' property of the form list-item
value.
When an ol element has a start
attribute or a reversed attribute, or both, the user agent
is expected to use the following steps to treat the attributes as a presentational hint for the 'counter-reset' property:
Let value be null.
If the element has a start attribute, then set
value to the result of parsing the attribute's value using the rules for
parsing integers.
If the element has a reversed attribute, then:
If value is an integer, then increment value by 1 and return
reversed(list-item) value.
Otherwise, return reversed(list-item).
Otherwise:
If value is an integer, then decrement value by 1 and return
list-item value.
Otherwise, there is no presentational hint.
@namespace "http://www.w3.org/1999/xhtml" ;
table { display : table; }
caption { display : table-caption; }
colgroup, colgroup[hidden] { display : table-column-group; }
col, col[hidden] { display : table-column; }
thead, thead[hidden] { display : table-header-group; }
tbody, tbody[hidden] { display : table-row-group; }
tfoot, tfoot[hidden] { display : table-footer-group; }
tr, tr[hidden] { display : table-row; }
td, th { display : table-cell; }
colgroup[hidden], col[hidden], thead[hidden], tbody[hidden],
tfoot[hidden], tr[hidden] {
visibility : collapse;
}
table {
box-sizing : border-box;
border-spacing : 2 px ;
border-collapse : separate;
text-indent : initial;
}
td, th { padding : 1 px ; }
th { font-weight : bold; }
caption { text-align : center; }
thead, tbody, tfoot, table > tr { vertical-align : middle; }
tr, td, th { vertical-align : inherit; }
thead, tbody, tfoot, tr { border-color : inherit; }
table[rules=none i], table[rules=groups i], table[rules=rows i],
table[rules=cols i], table[rules=all i], table[frame=void i],
table[frame=above i], table[frame=below i], table[frame=hsides i],
table[frame=lhs i], table[frame=rhs i], table[frame=vsides i],
table[frame=box i], table[frame=border i],
table[rules=none i] > tr > td, table[rules=none i] > tr > th,
table[rules=groups i] > tr > td, table[rules=groups i] > tr > th,
table[rules=rows i] > tr > td, table[rules=rows i] > tr > th,
table[rules=cols i] > tr > td, table[rules=cols i] > tr > th,
table[rules=all i] > tr > td, table[rules=all i] > tr > th,
table[rules=none i] > thead > tr > td, table[rules=none i] > thead > tr > th,
table[rules=groups i] > thead > tr > td, table[rules=groups i] > thead > tr > th,
table[rules=rows i] > thead > tr > td, table[rules=rows i] > thead > tr > th,
table[rules=cols i] > thead > tr > td, table[rules=cols i] > thead > tr > th,
table[rules=all i] > thead > tr > td, table[rules=all i] > thead > tr > th,
table[rules=none i] > tbody > tr > td, table[rules=none i] > tbody > tr > th,
table[rules=groups i] > tbody > tr > td, table[rules=groups i] > tbody > tr > th,
table[rules=rows i] > tbody > tr > td, table[rules=rows i] > tbody > tr > th,
table[rules=cols i] > tbody > tr > td, table[rules=cols i] > tbody > tr > th,
table[rules=all i] > tbody > tr > td, table[rules=all i] > tbody > tr > th,
table[rules=none i] > tfoot > tr > td, table[rules=none i] > tfoot > tr > th,
table[rules=groups i] > tfoot > tr > td, table[rules=groups i] > tfoot > tr > th,
table[rules=rows i] > tfoot > tr > td, table[rules=rows i] > tfoot > tr > th,
table[rules=cols i] > tfoot > tr > td, table[rules=cols i] > tfoot > tr > th,
table[rules=all i] > tfoot > tr > td, table[rules=all i] > tfoot > tr > th {
border-color : black;
}
The following rules are also expected to apply, as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
table[align=left i] { float : left; }
table[align=right i] { float : right; }
table[align=center i] { margin-inline : auto; }
thead[align=absmiddle i], tbody[align=absmiddle i], tfoot[align=absmiddle i],
tr[align=absmiddle i], td[align=absmiddle i], th[align=absmiddle i] {
text-align : center;
}
caption[align=bottom i] { caption-side : bottom; }
p[align=left i], h1[align=left i], h2[align=left i], h3[align=left i],
h4[align=left i], h5[align=left i], h6[align=left i] {
text-align : left;
}
p[align=right i], h1[align=right i], h2[align=right i], h3[align=right i],
h4[align=right i], h5[align=right i], h6[align=right i] {
text-align : right;
}
p[align=center i], h1[align=center i], h2[align=center i], h3[align=center i],
h4[align=center i], h5[align=center i], h6[align=center i] {
text-align : center;
}
p[align=justify i], h1[align=justify i], h2[align=justify i], h3[align=justify i],
h4[align=justify i], h5[align=justify i], h6[align=justify i] {
text-align : justify;
}
thead[valign=top i], tbody[valign=top i], tfoot[valign=top i],
tr[valign=top i], td[valign=top i], th[valign=top i] {
vertical-align : top;
}
thead[valign=middle i], tbody[valign=middle i], tfoot[valign=middle i],
tr[valign=middle i], td[valign=middle i], th[valign=middle i] {
vertical-align : middle;
}
thead[valign=bottom i], tbody[valign=bottom i], tfoot[valign=bottom i],
tr[valign=bottom i], td[valign=bottom i], th[valign=bottom i] {
vertical-align : bottom;
}
thead[valign=baseline i], tbody[valign=baseline i], tfoot[valign=baseline i],
tr[valign=baseline i], td[valign=baseline i], th[valign=baseline i] {
vertical-align : baseline;
}
td[nowrap], th[nowrap] { white-space : nowrap; }
table[rules=none i], table[rules=groups i], table[rules=rows i],
table[rules=cols i], table[rules=all i] {
border-style : hidden;
border-collapse : collapse;
}
table[border] { border-style : outset; } /* only if border is not equivalent to zero */
table[frame=void i] { border-style : hidden; }
table[frame=above i] { border-style : outset hidden hidden hidden; }
table[frame=below i] { border-style : hidden hidden outset hidden; }
table[frame=hsides i] { border-style : outset hidden outset hidden; }
table[frame=lhs i] { border-style : hidden hidden hidden outset; }
table[frame=rhs i] { border-style : hidden outset hidden hidden; }
table[frame=vsides i] { border-style : hidden outset; }
table[frame=box i], table[frame=border i] { border-style : outset; }
table[border] > tr > td, table[border] > tr > th,
table[border] > thead > tr > td, table[border] > thead > tr > th,
table[border] > tbody > tr > td, table[border] > tbody > tr > th,
table[border] > tfoot > tr > td, table[border] > tfoot > tr > th {
/* only if border is not equivalent to zero */
border-width : 1 px ;
border-style : inset;
}
table[rules=none i] > tr > td, table[rules=none i] > tr > th,
table[rules=none i] > thead > tr > td, table[rules=none i] > thead > tr > th,
table[rules=none i] > tbody > tr > td, table[rules=none i] > tbody > tr > th,
table[rules=none i] > tfoot > tr > td, table[rules=none i] > tfoot > tr > th,
table[rules=groups i] > tr > td, table[rules=groups i] > tr > th,
table[rules=groups i] > thead > tr > td, table[rules=groups i] > thead > tr > th,
table[rules=groups i] > tbody > tr > td, table[rules=groups i] > tbody > tr > th,
table[rules=groups i] > tfoot > tr > td, table[rules=groups i] > tfoot > tr > th,
table[rules=rows i] > tr > td, table[rules=rows i] > tr > th,
table[rules=rows i] > thead > tr > td, table[rules=rows i] > thead > tr > th,
table[rules=rows i] > tbody > tr > td, table[rules=rows i] > tbody > tr > th,
table[rules=rows i] > tfoot > tr > td, table[rules=rows i] > tfoot > tr > th {
border-width : 1 px ;
border-style : none;
}
table[rules=cols i] > tr > td, table[rules=cols i] > tr > th,
table[rules=cols i] > thead > tr > td, table[rules=cols i] > thead > tr > th,
table[rules=cols i] > tbody > tr > td, table[rules=cols i] > tbody > tr > th,
table[rules=cols i] > tfoot > tr > td, table[rules=cols i] > tfoot > tr > th {
border-width : 1 px ;
border-block-style : none;
border-inline-style : solid;
}
table[rules=all i] > tr > td, table[rules=all i] > tr > th,
table[rules=all i] > thead > tr > td, table[rules=all i] > thead > tr > th,
table[rules=all i] > tbody > tr > td, table[rules=all i] > tbody > tr > th,
table[rules=all i] > tfoot > tr > td, table[rules=all i] > tfoot > tr > th {
border-width : 1 px ;
border-style : solid;
}
table[rules=groups i] > colgroup {
border-inline-width : 1 px ;
border-inline-style : solid;
}
table[rules=groups i] > thead,
table[rules=groups i] > tbody,
table[rules=groups i] > tfoot {
border-block-width : 1 px ;
border-block-style : solid;
}
table[rules=rows i] > tr, table[rules=rows i] > thead > tr,
table[rules=rows i] > tbody > tr, table[rules=rows i] > tfoot > tr {
border-block-width : 1 px ;
border-block-style : solid;
}
In quirks mode, the following rules are also expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
table {
font-weight : initial;
font-style : initial;
font-variant : initial;
font-size : initial;
line-height : initial;
white-space : initial;
text-align : initial;
}
For the purposes of the CSS table model, the col element is expected to be treated
as if it was present as many times as its span attribute specifies.
For the purposes of the CSS table model, the colgroup element, if it contains no
col element, is expected to be treated as if it had as many such children as its
span attribute specifies.
For the purposes of the CSS table model, the colspan and
rowspan attributes on td and th
elements are expected to provide the
special knowledge regarding cells spanning rows and columns.
In HTML documents, the following rules are also expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
:is(table, thead, tbody, tfoot, tr) > form { display : none !important; }
The table element's cellspacing
attribute maps to the pixel length property 'border-spacing' on the
element.
The table element's cellpadding
attribute maps to the pixel length
properties 'padding-top', 'padding-right',
'padding-bottom', and 'padding-left' of any td and
th elements that have corresponding cells in the
table corresponding to the table element.
The table element's height attribute
maps to the dimension property 'height' on the table
element.
The table element's width attribute
maps to the dimension property (ignoring zero) 'width' on the
table element.
The col element's width attribute maps
to the dimension property 'width' on the col
element.
The thead, tbody, and tfoot elements' height attribute maps to the dimension property
'height' on the element.
The tr element's height attribute maps
to the dimension property 'height' on the tr element.
The td and th elements' height
attributes map to the dimension
property (ignoring zero) 'height' on the element.
The td and th elements' width
attributes map to the dimension
property (ignoring zero) 'width' on the element.
The thead, tbody, tfoot, tr,
td, and th elements, when they have an align
attribute whose value is an ASCII case-insensitive match for either the string "center" or the string "middle", are expected to center
text within themselves, as if they had their 'text-align' property set to 'center' in
a presentational hint, and to align
descendants to the center.
The thead, tbody, tfoot, tr,
td, and th elements, when they have an align
attribute whose value is an ASCII case-insensitive match for the string "left", are expected to left-align text within themselves, as if they had their
'text-align' property set to 'left' in a presentational hint, and to align descendants to the left.
The thead, tbody, tfoot, tr,
td, and th elements, when they have an align
attribute whose value is an ASCII case-insensitive match for the string "right", are expected to right-align text within themselves, as if they had their
'text-align' property set to 'right' in a presentational hint, and to align descendants to the right.
The thead, tbody, tfoot, tr,
td, and th elements, when they have an align
attribute whose value is an ASCII case-insensitive match for the string "justify", are expected to full-justify text within themselves, as if they had
their 'text-align' property set to 'justify' in a presentational hint, and to align descendants to the left.
User agents are expected to have a rule in their user agent style sheet that matches
th elements that have a parent node whose computed value for the
'text-align' property is its initial value, whose declaration block consists of just
a single declaration that sets the 'text-align' property to the value 'center'.
When a table, thead, tbody, tfoot,
tr, td, or th element has a background attribute set to a non-empty value, the new value is
expected to be encoding-parsed-and-serialized relative to the element's node document,
and if that does not return failure, the user agent is expected to treat the attribute as a presentational hint setting the element's
'background-image' property to the return value.
When a table, thead, tbody, tfoot,
tr, td, or th element has a bgcolor
attribute set, the new value is expected to be parsed using the rules for parsing a legacy
color value, and if that does not return failure, the user agent is expected to treat the
attribute as a presentational hint setting the element's
'background-color' property to the resulting color.
When a table element has a bordercolor
attribute, its value is expected to be parsed using the rules for parsing a legacy color
value, and if that does not return failure, the user agent is expected to treat the
attribute as a presentational hint setting the
element's 'border-top-color', 'border-right-color',
'border-bottom-color', and 'border-left-color' properties to the
resulting color.
The table element's border attribute maps to the pixel length properties
'border-top-width', 'border-right-width',
'border-bottom-width', 'border-left-width' on the element. If the
attribute is present but parsing the attribute's value using the rules for parsing
non-negative integers generates an error, a default value of 1px is expected to be used for
that property instead.
Rules marked "only if border is not equivalent to zero"
in the CSS block above is expected to only be applied if the border attribute mentioned in the selectors for the rule is not
only present but, when parsed using the rules for parsing non-negative integers, is
also found to have a value other than zero or to generate an error.
In quirks mode, a td element or a th element that has a
nowrap attribute but also has a width attribute whose value, when parsed using the rules for
parsing nonzero dimension values, is found to be a length (not an error or a number
classified as a percentage), is expected to have a presentational hint setting the element's 'white-space' property to
'normal', overriding the rule in the CSS block above that sets it to 'nowrap'.
In quirks mode, any element
with default margins that is the child of a
body, td, or th element and has no substantial previous siblings is expected to have a
user-agent level style sheet rule that sets its 'margin-block-start' property to
zero.
In quirks mode, any element
with default margins that is the child of a
body, td, or th element, has no substantial previous siblings, and is blank, is expected to have a user-agent level style sheet
rule that sets its 'margin-block-end' property to zero also.
In quirks mode, any element
with default margins that is the child of a
td or th element, has no substantial following siblings, and is blank, is expected to have a user-agent level style sheet
rule that sets its 'margin-block-start' property to zero.
In quirks mode, any p element that is the child of a td or th element and has
no substantial following siblings, is expected
to have a user-agent level style sheet rule that sets its 'margin-block-end' property
to zero.
@namespace "http://www.w3.org/1999/xhtml" ;
input, select, button, textarea {
letter-spacing : initial;
word-spacing : initial;
line-height : initial;
text-transform : initial;
text-indent : initial;
text-shadow : initial;
appearance : auto;
}
input:not([type=image i], [type=range i], [type=checkbox i], [type=radio i]) {
overflow : clip !important;
overflow-clip-margin: 0 !important;
}
input, select, textarea {
text-align: initial;
}
:autofill {
field-sizing: fixed !important;
}
input:is([type=reset i], [type=button i], [type=submit i]), button {
text-align: center;
}
input, button {
display: inline-block;
}
input[type=hidden i], input[type=file i], input[type=image i] {
appearance: none;
}
input:is([type=radio i], [type=checkbox i], [type=reset i], [type=button i],
[type=submit i], [type=color i], [type=search i]), select, button {
box-sizing: border-box;
}
textarea { white-space: pre-wrap; }
In quirks mode, the following rules are also expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
input:not([type=image i]), textarea { box-sizing : border-box; }
Each kind of form control is also described in the Widgets section, which describes the look and feel of the control.
For input elements where the type attribute
is not in the state or the Image Button state, and that are being
rendered, are expected to act as follows:
The inner display type is always 'flow-root'.
hr element@namespace "http://www.w3.org/1999/xhtml" ;
hr {
color : gray;
border-style : inset;
border-width : 1 px ;
margin-block : 0.5 em ;
margin-inline : auto;
overflow : hidden;
}
The following rules are also expected to apply, as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
hr[align=left i] { margin-left : 0 ; margin-right : auto; }
hr[align=right i] { margin-left : auto; margin-right : 0 ; }
hr[align=center i] { margin-left : auto; margin-right : auto; }
hr[color], hr[noshade] { border-style : solid; }
If an hr element has either a color attribute
or a noshade attribute, and furthermore also has a size attribute, and parsing that attribute's value using the
rules for parsing non-negative integers doesn't generate an error, then the user
agent is expected to use the parsed value divided by two as a pixel length for
presentational hints for the properties 'border-top-width',
'border-right-width', 'border-bottom-width', and
'border-left-width' on the element.
Otherwise, if an hr element has neither a color
attribute nor a noshade attribute, but does have a size attribute, and parsing that attribute's value using the
rules for parsing non-negative integers doesn't generate an error, then: if the
parsed value is one, then the user agent is expected to use the attribute as a presentational hint setting the element's
'border-bottom-width' to 0; otherwise, if the parsed value is greater than one, then
the user agent is expected to use the parsed value minus two as a pixel length for
presentational hints for the 'height' property on the element.
The width attribute on an hr element maps
to the dimension property 'width' on the element.
When an hr element has a color attribute, its
value is expected to be parsed using the rules for parsing a legacy color value, and
if that does not return failure, the user agent is expected to treat the attribute as a presentational hint setting the element's
'color' property to the resulting color.
fieldset and legend elements@namespace "http://www.w3.org/1999/xhtml" ;
fieldset {
display : block;
margin-inline : 2 px ;
border : groove 2 px ThreeDFace;
padding-block : 0.35 em 0.625 em ;
padding-inline : 0.75 em ;
min-inline-size : min-content;
}
legend {
padding-inline : 2 px ;
}
legend[align=left i] {
justify-self : left;
}
legend[align=center i] {
justify-self : center;
}
legend[align=right i] {
justify-self : right;
}
The fieldset element, when it generates a CSS box, is expected to act
as follows:
The element is expected to establish a new block formatting context.
The 'display' property is expected to act as follows:
If the computed value of 'display' is a value such that the outer display type is 'inline', then behave as 'inline-block'.
Otherwise, behave as 'flow-root'.
If the element has a rendered legend, then the border is expected to not be painted behind the rectangle defined as follows, using the writing mode of the fieldset:
The block-start edge of the rectangle is the smaller of the block-start edge of the
rendered legend's margin rectangle at its static position (ignoring transforms),
and the block-start outer edge of the fieldset's border.
The block-end edge of the rectangle is the larger of the block-end edge of the
rendered legend's margin rectangle at its static position (ignoring transforms),
and the block-end outer edge of the fieldset's border.
The inline-start edge of the rectangle is the smaller of the inline-start edge of the
rendered legend's border rectangle at its static position (ignoring transforms),
and the inline-start outer edge of the fieldset's border.
The inline-end edge of the rectangle is the larger of the inline-end edge of the
rendered legend's border rectangle at its static position (ignoring transforms),
and the inline-end outer edge of the fieldset's border.
The space allocated for the element's border on the block-start side is expected to be
the element's 'border-block-start-width' or the rendered legend's
margin box size in the fieldset's block-flow direction, whichever is
greater.
For the purpose of calculating the used 'block-size', if the computed 'block-size' is not 'auto', the space allocated for the rendered legend's margin box that spills out past the border, if any, is expected to be subtracted from the 'block-size'. If the content box's block-size would be negative, then let the content box's block-size be zero instead.
If the element has a rendered legend, then that element is expected to be the first child box.
The anonymous fieldset content box is expected to appear after the
rendered legend and is expected to contain the content (including the '::before'
and '::after' pseudo-elements) of the fieldset element except for the
rendered legend, if there is one.
The used value of the 'padding-top', 'padding-right', 'padding-bottom', and 'padding-left' properties are expected to be zero.
For the purpose of calculating the min-content inline size, use the greater of the min-content inline size of the rendered legend and the min-content inline size of the anonymous fieldset content box.
For the purpose of calculating the max-content inline size, use the greater of the max-content inline size of the rendered legend and the max-content inline size of the anonymous fieldset content box.
A fieldset element's rendered legend, if any, is expected to act as
follows:
The element is expected to establish a new formatting context for its contents. The type of this formatting context is determined by its 'display' value, as usual.
The 'display' property is expected to behave as if its computed value was blockified.
If the computed value of 'inline-size' is 'auto', then the used value is the fit-content inline size.
The element is expected to be positioned in the inline direction as is normal for blocks (e.g., taking into account margins and the 'justify-self' property).
The element's box is expected to be constrained in the inline direction by the inline
content size of the fieldset as if it had used its computed inline padding.
The element is expected to be positioned in the block-flow direction such that its border
box is centered over the border on the block-start side of the fieldset
element.
The embed, iframe, and video elements are expected to be
treated as replaced elements.
A canvas element that represents embedded content is
expected to be treated as a replaced element; the contents of such elements are the
element's bitmap, if any, or else a transparent black bitmap with the same
natural dimensions as the element. Other canvas elements are expected
to be treated as ordinary elements in the rendering model.
An object element that represents an image, plugin, or its
content navigable is expected to be treated as a replaced element.
Other object elements are expected to be treated as ordinary elements in the
rendering model.
The audio element, when it is exposing a user interface, is expected to be treated as a
replaced element about one line high, as wide as is necessary to expose the user
agent's user interface features. When an audio element is not exposing a user interface, the user agent is expected to force
its 'display' property to compute to 'none', irrespective of CSS rules.
Whether a video element is exposing a user interface is not expected to affect the size of the rendering;
controls are expected to be overlaid above the page content without causing any layout changes,
and are expected to disappear when the user does not need them.
When a video element represents a poster frame or frame of video, the poster frame
or frame of video is expected to be rendered at the largest size that maintains the aspect ratio
of that poster frame or frame of video without being taller or wider than the video
element itself, and is expected to be centered in the video element.
Any subtitles or captions are expected to be overlaid directly on top of their
video element, as defined by the relevant rendering rules; for WebVTT, those are the
rules for updating the display of WebVTT text tracks. [WEBVTT]
When the user agent starts exposing a user
interface for a video element, the user agent should run the rules for
updating the text track rendering of each of the text
tracks in the video element's list of text tracks that are showing and whose text track kind is one of subtitles or captions (e.g., for text
tracks based on WebVTT, the rules for updating the display of WebVTT text
tracks). [WEBVTT]
The following CSS rules are expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
iframe { border : 2 px inset; }
video { object-fit : contain; }
User agents are expected to render img elements and input elements
whose type attributes are in the Image Button state, according to the first applicable rules
from the following list:
alt attribute, or
Document is in quirks mode, and the element already has
natural dimensions (e.g., from the dimension attributes or CSS
rules)
input elements, the element
is expected to appear button-like to indicate that the element is a button.img element that represents some text and the
user agent does not expect this to changeimg element that represents nothing and the
user agent does not expect this to changeinput element that does not represent an image and the user agent does not expect this to changeThe icons mentioned above are expected to be relatively small so as not to disrupt most text but be easily clickable. In a visual environment, for instance, icons could be 16 pixels by 16 pixels square, or 1em by 1em if the images are scalable. In an audio environment, the icon could be a short bleep. The icons are intended to indicate to the user that they can be used to get to whatever options the UA provides for images, and, where appropriate, are expected to provide access to the context menu that would have come up if the user interacted with the actual image.
All animated images with the same absolute URL and the same image data are expected to be rendered synchronized to the same timeline as a group, with the timeline starting at the time of the least recent addition to the group.
When a user agent is to restart the animation for an img element
showing an animated image, all animated images with the same absolute URL and the
same image data in that img element's node document are expected to restart
their animation from the beginning.
The following CSS rules are expected to apply:
@namespace "http://www.w3.org/1999/xhtml" ;
img:is([sizes="auto" i], [sizes^="auto," i]) {
contain : size !important;
contain-intrinsic-size: 300px 150px;
}
The following CSS rules are expected to apply when the Document is in quirks
mode:
@namespace "http://www.w3.org/1999/xhtml" ;
img[align=left i] { margin-right : 3 px ; }
img[align=right i] { margin-left : 3 px ; }
The following CSS rules are expected to apply as presentational hints:
@namespace "http://www.w3.org/1999/xhtml" ;
iframe[frameborder='0'], iframe[frameborder=no i] { border : none; }
embed[align=left i], iframe[align=left i], img[align=left i],
input[type=image i][align=left i], object[align=left i] {
float : left;
}
embed[align=right i], iframe[align=right i], img[align=right i],
input[type=image i][align=right i], object[align=right i] {
float : right;
}
embed[align=top i], iframe[align=top i], img[align=top i],
input[type=image i][align=top i], object[align=top i] {
vertical-align : top;
}
embed[align=baseline i], iframe[align=baseline i], img[align=baseline i],
input[type=image i][align=baseline i], object[align=baseline i] {
vertical-align : baseline;
}
embed[align=texttop i], iframe[align=texttop i], img[align=texttop i],
input[type=image i][align=texttop i], object[align=texttop i] {
vertical-align : text-top;
}
embed[align=absmiddle i], iframe[align=absmiddle i], img[align=absmiddle i],
input[type=image i][align=absmiddle i], object[align=absmiddle i],
embed[align=abscenter i], iframe[align=abscenter i], img[align=abscenter i],
input[type=image i][align=abscenter i], object[align=abscenter i] {
vertical-align : middle;
}
embed[align=bottom i], iframe[align=bottom i], img[align=bottom i],
input[type=image i][align=bottom i], object[align=bottom i] {
vertical-align : bottom;
}
When an embed, iframe, img, or object
element, or an input element whose type
attribute is in the Image Button state, has an align attribute whose value is an ASCII case-insensitive match for
the string "center" or the string "middle", the user
agent is expected to act as if the element's 'vertical-align' property was set to a
value that aligns the vertical middle of the element with the parent element's baseline.
The hspace attribute of embed,
img, or object elements, and input elements with a type attribute in the Image
Button state, maps to the dimension
properties 'margin-left' and 'margin-right' on the element.
The vspace attribute of embed,
img, or object elements, and input elements with a type attribute in the Image
Button state, maps to the dimension
properties 'margin-top' and 'margin-bottom' on the element.
When an img element, object element, or input element
with a type attribute in the Image Button state has a border attribute whose value, when parsed using the rules for
parsing non-negative integers, is found to be a number greater than zero, the user agent is
expected to use the parsed value for eight presentational hints: four setting the
parsed value as a pixel length for the element's 'border-top-width',
'border-right-width', 'border-bottom-width', and
'border-left-width' properties, and four setting the element's
'border-top-style', 'border-right-style',
'border-bottom-style', and 'border-left-style' properties to the value
'solid'.
The width and height attributes on an img element's dimension attribute source map to the dimension properties
'width' and 'height' on the img element respectively. They
similarly map to the aspect-ratio property (using dimension rules) of the
img element.
The width and height
attributes on embed, iframe, object, and video
elements, and input elements with a type
attribute in the Image Button state and that either
represents an image or that the user expects will eventually represent an image, map to the dimension properties
'width' and 'height' on the element respectively.
The width and height
attributes map to the aspect-ratio property (using dimension rules) on
img and video elements, and input elements with a type attribute in the Image
Button state.
The width and height attributes map to the aspect-ratio property
on canvas elements.
Shapes on an image map are expected to act, for the purpose of the CSS cascade, as
elements independent of the original area element that happen to match the same style
rules but inherit from the img or object element.
For the purposes of the rendering, only the 'cursor' property is expected to have any effect on the shape.
The CSS Basic User Interface specification calls elements that can have a native appearance widgets, and defines whether to use that native appearance depending on the 'appearance' property. That logic, in turn, depends on whether on whether each the element is classified as a devolvable widget or non-devolvable widget. This section defines which elements match these concepts for HTML, what their native appearance is, and any particularity of their devolved state or primitive appearance. [CSSUI]
The following elements can have a native appearance for the purpose of the CSS 'appearance' property.
Several widgets have their rendering controlled by the 'writing-mode' CSS property. For the purposes of those widgets, we have the following definitions.
A vertical writing mode is when resolving the 'writing-mode' property of the control results in a computed value of either 'vertical-rl', 'vertical-lr', 'sideways-rl' or 'sideways-lr'.
When an element uses button layout, it is a devolvable widget, and it's native appearance is that of a button.
button elementThe button element, when it generates a CSS box, is expected to
depict a button and to use button layout whose anonymous button content
box's contents (if there is an anonymous button content box) are the child
boxes the element's box would otherwise have.
details and summary elements@namespace "http://www.w3.org/1999/xhtml" ;
details, summary {
display : block;
}
details > summary:first-of-type {
display : list-item;
counter-increment : list-item 0 ;
list-style : disclosure-closed inside;
}
details[open] > summary:first-of-type {
list-style-type : disclosure-open;
}
The details element is expected to have an internal shadow tree with
three child elements:
The summary element that this slot represents is expected to allow
the user to request the details be shown or hidden.
The second child element is a slot that is expected to take the
details element's remaining descendants, if any. This element has no contents.
This element is expected to match the '::details-content' pseudo-element.
This element is expected to have its style attribute set to
"display: block; content-visibility: hidden;" when the
details element does not have an open
attribute. When it does have the open attribute, the
style attribute is expected to be set to
"display: block;".
The third child element is either a link or style
element with the following styles for the default summary:
:host summary {
display : list-item;
counter-increment : list-item 0 ;
list-style : disclosure-closed inside;
}
:host([open]) summary {
list-style-type : disclosure-open;
}
input element as a text entry widgetAn input element whose type attribute is in
the Text, Telephone, URL, or
Email state, is a devolvable widget. Its
expected native appearance is to render as an 'inline-block' box depicting
a one-line text control.
An input element whose type attribute is in
the Search state is a devolvable widget.
Its expected native appearance is to render as an 'inline-block' box
depicting a one-line text control. If the computed value of the element's
'appearance' property is not 'textfield', it may have a distinct style
indicating that it is a search field.
An input element whose type attribute is in
the Password state is a devolvable
widget. Its expected native appearance is to render as an
'inline-block' box depicting a one-line text control that obscures data entry.
For input elements whose type attribute is
in one of the above states, the used value of the 'line-height' property
must be a length value that is no smaller than what the used value would be for
'line-height: normal'.
If these text controls provide a text selection, then, when the user changes the current
selection, the user agent is expected to queue an element task on the user
interaction task source given the input element to fire an event named select
at the element, with the bubbles attribute initialized to
true.
An input element whose type attribute is
in one of the above states is an element with default preferred size, and user
agents are expected to apply the 'field-sizing' CSS property to the element. User
agents are expected to determine the inline size of its intrinsic size
by the following steps:
If the 'field-sizing' property on the element has a computed value
of 'content', the inline size is
determined by the text which the element shows. The text is either a
value or a short hint specified by the
placeholder attribute. User agents may take the
text caret size into account in the inline size.
If the element has a size attribute, and parsing that
attribute's value using the rules for parsing non-negative integers doesn't
generate an error, return the value obtained from applying the converting a character
width to pixels algorithm to the value of the attribute.
Otherwise, return the value obtained from applying the converting a character width to pixels algorithm to the number 20.
These text controls are expected to be scroll containers and support scrolling in the inline axis, but not the block axis.
input element as domain-specific widgetsAn input element whose type attribute is in
the Date state is a devolvable widget
expected to render as an 'inline-block' box depicting a date control.
An input element whose type attribute is in
the Month state is a devolvable widget
expected to render as an 'inline-block' box depicting a month control.
An input element whose type attribute is in
the Week state is a devolvable widget
expected to render as an 'inline-block' box depicting a week control.
An input element whose type attribute is in
the Time state is a devolvable widget
expected to render as an 'inline-block' box depicting a time control.
An input element whose type attribute is in
the Local Date and Time state is a
devolvable widget expected to render as an 'inline-block' box depicting
a local date and time control.
An input element whose type attribute is in
the Number state is a devolvable widget
expected to render as an 'inline-block' box depicting a number control.
An input element whose type attribute is in
the Number state is an
element with default preferred size, and user agents are expected to apply the
'field-sizing' CSS property to the element. The block size of the
intrinsic size is about one line high. If the 'field-sizing' property
on the element has a computed value of
'content', the inline size of the
intrinsic size is expected to be about as wide as necessary to show the current
value. Otherwise, the inline size of the
intrinsic size is expected to be about as wide as necessary to show the widest
possible value.
An input element whose type attribute is in
the Date,
Month,
Week, Time,
or Local Date and Time state, is expected to
be about one line high, and about as wide as necessary to show the widest possible value.
input element as a range controlAn input element whose type attribute is in
the Range state is a non-devolvable
widget. Its expected native appearance is to render as an
'inline-block' box depicting a slider control.
When this control has a horizontal writing mode, the control is expected to be a horizontal slider. Its lowest value is on the right if the 'direction' property has a computed value of 'rtl', and on the left otherwise. When this control has a vertical writing mode, it is expected to be a vertical slider. Its lowest value is on the bottom if the 'direction' property has a computed value of 'rtl', and on the top otherwise.
Predefined suggested values (provided by the list
attribute) are expected to be shown as tick marks on the slider, which the slider can snap to.
input element as a color
wellAn input element whose type attribute is in
the Color state is expected to depict a color well,
which, when activated, provides the user with a color picker (e.g. a color wheel or color
palette) from which the color can be changed. The element, when it generates a CSS
box, is expected to use button layout, that has no child boxes of the
anonymous button content box. The anonymous button content box is
expected to have a presentational hint setting the
'background-color' property to the element's value.
Predefined suggested values (provided by the list
attribute) are expected to be shown in the color picker interface, not on the color well
itself.
input element as a checkbox and radio button widgetsAn input element whose type attribute is in
the Checkbox state is a non-devolvable
widget expected to render as an 'inline-block' box containing a single
checkbox control, with no label.
An input element whose type attribute is in
the Radio Button state is a non-devolvable
widget expected to render as an 'inline-block' box containing a single radio
button control, with no label.
input element as a file upload controlAn input element whose type attribute is in
the File Upload state, when it generates a CSS
box, is expected to render as an 'inline-block' box containing a span of text
giving the filename(s) of the selected
files, if any, followed by a button that, when activated, provides the user with a file
picker from which the selection can be changed. The button is expected to use button
layout and match the '::file-selector-button' pseudo-element. The contents of
its anonymous button content box are expected to be
implementation-defined (and possibly locale-specific) text, for example "Choose
file".
User agents may handle an input element whose
type attribute is in the
File Upload state as an
element with default preferred size, and user agents may apply the
'field-sizing' CSS property to the element. If the 'field-sizing'
property on the element has a computed value of
'content', the intrinsic size of the
element is expected to depend on its content such as the '::file-selector-button'
pseudo-element and chosen file names.
input element as a buttonAn input element whose type attribute is in
the Submit Button, Reset Button, or Button state, when it generates a CSS box, is
expected to depict a button and use button layout and the contents of the
anonymous button content box are expected to be the text of the element's value attribute, if any, or text derived from the element's type attribute in an implementation-defined (and
probably locale-specific) fashion, if not.
marquee element@namespace "http://www.w3.org/1999/xhtml" ;
marquee {
display : inline-block;
text-align : initial;
overflow : hidden !important;
}
The marquee element, while turned on, is
expected to render in an animated fashion according to its attributes as follows:
behavior attribute is in the
scroll stateSlide the contents of the element in the direction described by the direction attribute as defined below, such that it begins
off the start side of the marquee, and ends flush with the inner end side.
Once the animation has ended, the user agent is expected to increment the marquee current loop index. If the element is still turned on after this, then the user agent is expected to restart the animation.
behavior attribute is in the
slide stateSlide the contents of the element in the direction described by the direction attribute as defined below, such that it begins
off the start side of the marquee, and ends off the end side of the
marquee.
Once the animation has ended, the user agent is expected to increment the marquee current loop index. If the element is still turned on after this, then the user agent is expected to restart the animation.
behavior attribute is in the
alternate stateWhen the marquee current loop index is even (or zero), slide the contents of the
element in the direction described by the direction
attribute as defined below, such that it begins flush with the start side of the
marquee, and ends flush with the end side of the marquee.
When the marquee current loop index is odd, slide the contents of the element in
the opposite direction than that described by the direction attribute as defined below, such that it begins
flush with the end side of the marquee, and ends flush with the start side of the
marquee.
Once the animation has ended, the user agent is expected to increment the marquee current loop index. If the element is still turned on after this, then the user agent is expected to continue the animation.
The direction attribute has the meanings described
in the following table:
direction attribute state
| Direction of animation | Start edge | End edge | Opposite direction |
|---|---|---|---|---|
| left | ← Right to left | Right | Left | → Left to Right |
| right | → Left to Right | Left | Right | ← Right to left |
| up | ↑ Up (Bottom to Top) | Bottom | Top | ↓ Down (Top to Bottom) |
| down | ↓ Down (Top to Bottom) | Top | Bottom | ↑ Up (Bottom to Top) |
In any case, the animation should proceed such that there is a delay given by the marquee scroll interval between each frame, and such that the content moves at most the distance given by the marquee scroll distance with each frame.
When a marquee element has a bgcolor
attribute set, the value is expected to be parsed using the rules for parsing a legacy color
value, and if that does not return failure, the user agent is expected to treat the
attribute as a presentational hint setting the element's
'background-color' property to the resulting color.
The width and height attributes on a marquee element
map to the dimension properties
'width' and 'height' on the element respectively.
The natural height of a marquee element with its direction attribute in the up or down states is 200 CSS
pixels.
The vspace attribute of a
marquee element maps to the dimension
properties 'margin-top' and 'margin-bottom' on the element. The
hspace attribute of a marquee
element maps to the dimension properties
'margin-left' and 'margin-right' on the element.
meter element@namespace "http://www.w3.org/1999/xhtml" ;
meter { appearance : auto; }
The meter element is a devolvable widget. Its expected native
appearance is to render as an 'inline-block' box with a 'block-size'
of '1em' and a 'inline-size' of '5em', a 'vertical-align' of '-0.2em', and
with its contents depicting a gauge.
When this element has a horizontal writing mode, the depiction is expected to be of a horizontal gauge. Its minimum value is on the right if the 'direction' property has a computed value of 'rtl', and on the left otherwise. When this element has a vertical writing mode, it is expected to depict a vertical gauge. Its minimum value is on the bottom if the 'direction' property has a computed value of 'rtl', and on the top otherwise.
User agents are expected to use a presentation consistent with platform conventions for gauges, if any.
progress element@namespace "http://www.w3.org/1999/xhtml" ;
progress { appearance : auto; }
The progress element is a devolvable widget. Its expected
native appearance is to render as an 'inline-block' box with a
'block-size' of '1em' and a 'inline-size' of '10em', and a
'vertical-align' of '-0.2em'.
When the this
element has a horizontal writing mode, the element is expected to be depicted as a
horizontal progress bar. The start is on the right and the end is on the left if the
'direction' property on this element has a computed value of 'rtl', and
with the start on the left and the end on the right otherwise. When this element has a
vertical writing mode, it is expected to be depicted as a vertical progress bar. The
start is on the bottom and the end is on the top if the 'direction' property on this
element has a computed value of 'rtl', and with the start on the top and the end on
the bottom otherwise.
User agents are expected to use a presentation consistent with platform conventions for progress bars. In particular, user agents are expected to use different presentations for determinate and indeterminate progress bars. User agents are also expected to vary the presentation based on the dimensions of the element.
select elementThe select element is an element with default preferred size, and
user agents are expected to apply the 'field-sizing' CSS property to
select elements.
A select element is either a list box or a drop-down box, depending on its attributes.
A select element whose multiple
attribute is present is expected to render as a multi-select list box.
A select element whose multiple
attribute is absent, and whose display size is greater
than 1, is expected to render as a single-select list box.
When the element renders as a list box, it is a devolvable widget
expected to render as an 'inline-block' box. The inline size of its
intrinsic size is the width of the select's labels plus
the width of a scrollbar. The block size of its intrinsic size is
determined by the following steps:
If the 'field-sizing' property on the element has a computed value of 'content', return the height necessary to contain all rows for items.
If the size attribute is absent or it has no valid
value, return the height necessary to contain four rows.
Otherwise, return the height necessary to contain as many rows for items as given by the element's display size.
A select element whose multiple
attribute is absent, and whose display size is 1, is
expected to render as an 'inline-block' one-line drop-down box.
The inline size of its intrinsic size is the
width of the select's labels. If the 'field-sizing'
property on the element has a computed value of
'content', the inline size of the
intrinsic size depends on the shown text. The shown text is typically the label of
an option of which selectedness is
set to true.
When the element renders as a drop-down box, it is a devolvable
widget. Its appearance in the devolved state, as well as its appearance when the
computed value of the element's 'appearance' property is
'menulist-button', is that of a drop-down box, including a "drop-down button",
but not necessarily rendered using a native control of the host operating system. In such a state,
CSS properties such as 'color', 'background-color', and 'border' should
not be disregarded (as is generally permissible when rendering an element according to its
native appearance).
In either case (list box or drop-down box), the element's items are
expected to be the element's list of options,
with the element's optgroup element children
providing headers for groups of options where applicable.
An optgroup element is expected to be rendered by displaying the element's label attribute.
An option element is expected to be rendered by displaying the element's label, indented under its optgroup element if it
has one.
Each sequence of one or more child hr element siblings may be rendered as a single
separator.
If a select element contains a placeholder label option, the user
agent is expected to render that option in a manner that conveys that it is a label,
rather than a valid option of the control. This can include preventing the placeholder label
option from being explicitly selected by the user. When the placeholder label
option's selectedness is true, the control
is expected to be displayed in a fashion that indicates that no valid option is currently
selected.
User agents are expected to render the labels in a select in such a manner that
any alignment remains consistent whether the label is being displayed as part of the page or in a
menu control.
textarea elementThe textarea element is a devolvable widget expected to render as an
'inline-block' box depicting a multiline text control. If this multiline text control
provides a selection, then, when the user changes the current selection, the user agent is
expected to queue an element task on the user interaction task source
given the textarea element to fire an event
named select at the element, with the bubbles attribute initialized to true.
The textarea element is an element with default preferred size, and
user agents are expected to apply the 'field-sizing' CSS property to
textarea elements.
If the 'field-sizing' property on the element has a computed value
of 'content', the intrinsic size is
determined from the text which the element shows. The text is either a
raw value or a short hint specified by the
placeholder attribute. User agents may take the
text caret size into account in the intrinsic size. Otherwise, its
intrinsic size is computed from textarea effective width and
textarea effective height (as defined below).
User agents are expected to apply the 'white-space' CSS property to
textarea elements. For historical reasons, if the element has a wrap attribute whose value is an ASCII
case-insensitive match for the string "off", then the user agent is expected to treat the attribute as a presentational hint setting the element's
'white-space' property to 'pre'.
User agents are expected to render frameset elements as a box with the height and
width of the viewport, with a surface rendered according to the following layout
algorithm:
The cols and rows variables are lists of zero or more pairs consisting of a number and a unit, the unit being one of percentage, relative, and absolute.
Use the rules for parsing a list of dimensions to parse the value of the
element's cols attribute, if there is one.
Let cols be the result, or an empty list if there is no such attribute.
Use the rules for parsing a list of dimensions to parse the value of the
element's rows attribute, if there is one.
Let rows be the result, or an empty list if there is no such attribute.
For any of the entries in cols or rows that have the number zero and the unit relative, change the entry's number to one.
If cols has no entries, then add a single entry consisting of the value 1 and the unit relative to cols.
If rows has no entries, then add a single entry consisting of the value 1 and the unit relative to rows.
Invoke the algorithm defined below to convert a list of dimensions to a list of pixel
values using cols as the input list, and the width of the surface that the
frameset is being rendered into, in CSS pixels, as the
input dimension. Let sized cols be the resulting list.
Invoke the algorithm defined below to convert a list of dimensions to a list of pixel
values using rows as the input list, and the height of the surface that the
frameset is being rendered into, in CSS pixels, as the
input dimension. Let sized rows be the resulting list.
Split the surface into a grid of w×h rectangles, where w is the number of entries in sized cols and h is the number of entries in sized rows.
Size the columns so that each column in the grid is as many CSS pixels wide as the corresponding entry in the sized cols list.
Size the rows so that each row in the grid is as many CSS pixels high as the corresponding entry in the sized rows list.
Let children be the list of frame and frameset elements
that are children of the frameset element
for which the algorithm was invoked.
For each row of the grid of rectangles created in the previous step, from top to bottom, run these substeps:
For each rectangle in the row, from left to right, run these substeps:
If there are any elements left in children, take the first element in the list, and assign it to the rectangle.
If this is a frameset element, then recurse the entire frameset
layout algorithm for that frameset element, with the rectangle as the
surface.
Otherwise, it is a frame element; render its content
navigable, positioned and sized to fit the rectangle.
If there are any elements left in children, remove the first element from children.
If the frameset element has a border, draw an outer set of borders
around the rectangles, using the element's frame border color.
For each rectangle, if there is an element assigned to that rectangle, and that element has a border, draw an inner set of borders around that rectangle, using the element's frame border color.
For each (visible) border that does not abut a rectangle that is assigned a
frame element with a noresize
attribute (including rectangles in further nested frameset elements), the user
agent is expected to allow the user to move the border, resizing the rectangles within, keeping
the proportions of any nested frameset grids.
User agents working with integer values for frame widths (as opposed to user agents that can lay frames out with subpixel accuracy) are expected to distribute the remainder first to the last entry whose unit is relative, then equally (not proportionally) to each entry whose unit is percentage, then equally (not proportionally) to each entry whose unit is absolute, and finally, failing all else, to the last entry.
The contents of a frame element that does not have a frameset parent
are expected to be rendered as transparent black; the user agent is expected to not
render its content navigable in this case, and its content navigable is
expected to have a viewport with zero width and zero height.
User agents are expected to allow the user to control aspects of hyperlink activation and form submission, such as which navigable is to be used for the subsequent navigation.
User agents are expected to allow users to discover the destination of hyperlinks and of forms before triggering their navigation.
User agents are expected to inform the user of whether a hyperlink includes hyperlink auditing, and to let them know at a minimum which domains will be contacted as part of such auditing.
User agents may allow users to navigate navigables to the URLs indicated by the cite attributes on q,
blockquote, ins, and del elements.
User agents may surface hyperlinks created by link
elements in their user interface, as discussed previously.
title attributeUser agents are expected to expose the advisory information of elements upon user request, and to make the user aware of the presence of such information.
On interactive graphical systems where the user can use a pointing device, this could take the form of a tooltip. When the user is unable to use a pointing device, then the user agent is expected to make the content available in some other fashion, e.g. by making the element a focusable area and always displaying the advisory information of the currently focused element, or by showing the advisory information of the elements under the user's finger on a touch device as the user pans around the screen.
U+000A LINE FEED (LF) characters are expected to cause line breaks in the tooltip; U+0009 CHARACTER TABULATION (tab) characters are expected to render as a nonzero horizontal shift that lines up the next glyph with the next tab stop, with tab stops occurring at points that are multiples of 8 times the width of a U+0020 SPACE character.
The current text editing caret (i.e. the active range, if it is empty and in an editing host), if any, is expected to act like an inline replaced element with the vertical dimensions of the caret and with zero width for the purposes of the CSS rendering model.
User agents are expected to honor the Unicode semantics of text that is exposed in user interfaces, for example supporting the bidirectional algorithm in text shown in dialogs, title bars, popup menus, and tooltips. Text from the contents of elements is expected to be rendered in a manner that honors the directionality of the element from which the text was obtained. Text from attributes is expected to be rendered in a manner that honours the directionality of the attribute.
A string provided by a script (e.g. the argument to window.alert()) is expected to be treated as an independent set of one or
more bidirectional algorithm paragraphs when displayed, as defined by the bidirectional algorithm,
including, for instance, supporting the paragraph-breaking behavior of U+000A LINE FEED (LF)
characters. For the purposes of determining the paragraph level of such text in the bidirectional
algorithm, this specification does not provide a higher-level override of rules P2 and
P3. [BIDI]
When necessary, authors can enforce a particular direction for a given paragraph by starting it with the Unicode U+200E LEFT-TO-RIGHT MARK or U+200F RIGHT-TO-LEFT MARK characters.
When the user actually obtains a physical form (or
a representation of a physical form) of a Document, the user agent is expected to
create a new rendering of the Document for the print media.
HTML user agents may, in certain circumstances, find themselves rendering non-HTML documents that use vocabularies for which they lack any built-in knowledge. This section provides for a way for user agents to handle such documents in a somewhat useful manner.
While a Document is an unstyled document, the user agent is expected
to render an unstyled document view.
An unstyled document view is one where the DOM is not rendered according to CSS
(which would, since there are no applicable styles in this context, just result in a wall of
text), but is instead rendered in a manner that is useful for a developer. This could consist of
just showing the Document object's source, maybe with syntax highlighting, or it
could consist of displaying just the DOM tree, or simply a message saying that the page is not a
styled document.
Features listed in this section will trigger warnings in conformance checkers.
Authors should not specify a border attribute on an
img element. If the attribute is present, its value must be the string "0". CSS should be used instead.
Authors should not specify a charset attribute on a
script element. If the attribute is present, its value must be an ASCII
case-insensitive match for "utf-8". (This has no effect in a
document that conforms to the requirements elsewhere in this standard of being encoded as
UTF-8.)
Authors should not specify a language attribute on a
script element. If the attribute is present, its value must be an ASCII
case-insensitive match for the string "JavaScript" and either the
type attribute must be omitted or its value must be an
ASCII case-insensitive match for the string "text/javascript".
The attribute should be entirely omitted instead (with the value "JavaScript", it has no effect), or replaced with use of the type attribute.
Authors should not specify a value for the type
attribute on script elements that is the empty string or a JavaScript MIME type
essence match. Instead, they should omit the attribute, which has the same effect.
Authors should not specify a type attribute on a
style element. If the attribute is present, its value must be an ASCII
case-insensitive match for "text/css".
Authors should not specify the name attribute on
a elements. If the attribute is present, its value must not be the empty string and
must neither be equal to the value of any of the IDs in the
element's tree other than the element's own ID, if
any, nor be equal to the value of any of the other name
attributes on a elements in the element's tree. If this attribute is
present and the element has an ID, then the attribute's value
must be equal to the element's ID. In earlier versions of the
language, this attribute was intended as a way to specify possible targets for fragments in URLs. The id attribute should be used instead.
Authors should not, but may despite requirements to the contrary elsewhere in this
specification, specify the maxlength and size attributes on input elements whose type attributes are in the Number state. One valid reason for using these attributes
regardless is to help legacy user agents that do not support input elements with
type="number" to still render the text control with a useful width.
To ease the transition from HTML4 Transitional documents to the language defined in this specification, and to discourage certain features that are only allowed in very few circumstances, conformance checkers must warn the user when the following features are used in a document. These are generally old obsolete features that have no effect, and are allowed only to distinguish between likely mistakes (regular conformance errors) and mere vestigial markup or unusual and discouraged practices (these warnings).
The following features must be categorized as described above:
The presence of a border attribute on an
img element if its value is the string "0".
The presence of a charset attribute on a
script element if its value is an ASCII case-insensitive match for
"utf-8".
The presence of a language attribute on a
script element if its value is an ASCII case-insensitive match for the
string "JavaScript" and if there is no type attribute or there is and its value is an ASCII
case-insensitive match for the string "text/javascript".
The presence of a type attribute on a
script element if its value is a JavaScript MIME type essence
match.
The presence of a type attribute on a
style element if its value is an ASCII case-insensitive match for
"text/css".
The presence of a name attribute on an a
element, if its value is not the empty string.
The presence of a maxlength attribute on an
input element whose type attribute is in the
Number state.
The presence of a size attribute on an
input element whose type attribute is in the
Number state.
Conformance checkers must distinguish between pages that have no conformance errors and have none of these obsolete features, and pages that have no conformance errors but do have some of these obsolete features.
Elements in the following list are entirely obsolete, and must not be used by authors:
appletacronymUse abbr instead.
bgsoundUse audio instead.
dirUse ul instead.
frameframesetEither use iframe and CSS instead, or use server-side includes to generate complete pages with the various invariant parts merged in.
isindexUse an explicit form and text control combination instead.
keygenFor enterprise device management use cases, use native on-device management capabilities.
For certificate enrollment use cases, use the Web Cryptography API to generate a keypair for the certificate, and then export the certificate and key to allow the user to install them manually. [WEBCRYPTO]
listingmenuitemTo implement a custom context menu, use script to handle the contextmenu event.
nextidUse GUIDs instead.
noembedparamUse the data attribute of the object element to set the
URL of the external resource.
plaintextUse the "text/plain" MIME type instead.
rbProviding the ruby base directly inside the ruby element or using nested
ruby elements is sufficient.
strikeUse del instead if the element is marking an edit, otherwise use s instead.
xmpUse pre and code instead, and escape "<" and "&" characters as "<" and "&" respectively.
basefontbigblinkcenterfontmarqueeUse appropriate elements or CSS instead.
Where the tt element would have been used for marking up keyboard input,
consider the kbd element; for variables, consider the var element; for
computer code, consider the code element; and for computer output, consider the
samp element.
Similarly, if the big element is being used to denote a heading, consider using
the h1 element; if it is being used for marking up important passages, consider the
strong element; and if it is being used for highlighting text for reference
purposes, consider the mark element.
See also the text-level semantics usage summary for more suggestions with examples.
The following attributes are obsolete (though the elements are still part of the language), and must not be used by authors:
charset on a elementsUse an HTTP `Content-Type` header on the linked resource instead.
charset on script
elements (except as noted in the previous section)Omit the attribute. Both documents and scripts are required to use UTF-8, so
it is redundant to specify it on the script element since it inherits from the
document.
coords on a elementsmethods on a elementsUse the HTTP OPTIONS feature instead.
name on a elements (except as noted in the previous section)name on embed elementsname on img elementsUse the id attribute instead.
rev on a elementsUse the rel
attribute instead, with an opposite term. (For example, instead of
rev="made", use rel="author".)
urn on a elementsSpecify the preferred persistent identifier using the href attribute instead.
accept on form elementsUse the accept attribute directly on the input elements instead.
hreflang on area
elementsThese attributes do not do anything useful, and for historical reasons there are no
corresponding IDL attributes on area elements. Omit them altogether.
nohref on area elementsOmitting the href
attribute is sufficient; the nohref attribute is
unnecessary. Omit it altogether.
profile on head elementsUnnecessary. Omit it altogether.
manifest on html elementsUse service workers instead. [SW]
version on html elementsUnnecessary. Omit it altogether.
ismap on input elementsUnnecessary. Omit it altogether. All input elements with a type attribute in the Image
Button state are processed as server-side image maps.
usemap on input elementsUse the img element for image maps.
longdesc on iframe elementsUse a regular a element to link to the
description, or (in the case of images) use an image
map to provide a link from the image to the image's
description.
lowsrc on img elementsUse a progressive JPEG image (given in the src attribute),
instead of using two separate images.
target on link elementsUnnecessary. Omit it altogether.
type on menu elementsTo implement a custom context menu, use script to handle the contextmenu event. For toolbar menus, omit the
attribute.
label on menu elementscontextmenu on all elementsTo implement a custom context menu, use script to handle the contextmenu event.
scheme on meta elementsUse only one scheme per field, or make the scheme declaration part of the value.
archive on object elementsclassid on object elementscode on object elementscodebase on object elementsdeclare on object elementsRepeat the object element completely each time the resource is to be reused.
standby on object elementsOptimize the linked resource so that it loads quickly or, at least, incrementally.
typemustmatch on object elementsAvoid using object elements with untrusted resources.
language on script elements (except as noted in the previous section)Omit the attribute for JavaScript; for data blocks, use
the type attribute instead.
event on script elementsUse DOM events mechanisms to register event listeners. [DOM]
type on style elements (except as noted in the previous section)Omit the attribute for CSS; for data blocks, use
script as the container instead of style.
datapagesize on table elementsUnnecessary. Omit it altogether.
summary on table elementsUse one of the techniques for describing
tables given in the table section instead.
abbr on td elementsUse text that begins in an unambiguous and terse manner, and include any more elaborate text after that. The title attribute can also be useful in including more detailed text, so that the cell's contents can be made terse. If it's a heading, use th (which has an abbr attribute).
axis on td and th elementsscope on td elementsUse th elements for heading cells.
datasrc on a, button, div, frame, iframe, img, input, label, legend, marquee, object, option, select, span, table, and textarea elementsdatafld on a, button, div, fieldset, frame, iframe, img, input, label, legend, marquee, object, select, span, and textarea elementsUse script and a mechanism such as XMLHttpRequest to populate the page dynamically. [XHR]
dropzone on all elementsUse script to handle the dragenter and dragover events instead.
alink on body elementsbgcolor on body elementsbottommargin on body elementsleftmargin on body elementslink on body elementsmarginheight on body elementsmarginwidth on body elementsrightmargin on body elementstext on body elementstopmargin on body elementsvlink on body elementsclear on br elementsalign on caption elementsalign on col elementschar on col elementscharoff on col elementsvalign on col elementswidth on col elementsalign on div elementscompact on dl elementsalign on embed elementshspace on embed elementsvspace on embed elementsalign on hr elementscolor on hr elementsnoshade on hr elementssize on hr elementswidth on hr elementsalign on h1—h6 elementsalign on iframe elementsallowtransparency on iframe elementsframeborder on iframe elementsframespacing on iframe elementshspace on iframe elementsmarginheight on iframe elementsmarginwidth on iframe elementsscrolling on iframe elementsvspace on iframe elementsalign on input elementsborder on input elementshspace on input elementsvspace on input elementsalign on img elementsborder on img elements (except as noted in the previous section)hspace on img elementsvspace on img elementsalign on legend elementstype on li elementscompact on menu elementsalign on object elementsborder on object elementshspace on object elementsvspace on object elementscompact on ol elementsalign on p elementswidth on pre elementsalign on table elementsbgcolor on table elementsborder on table elementsbordercolor on table elementscellpadding on table elementscellspacing on table elementsframe on table elementsheight on table elementsrules on table elementswidth on table elementsalign on tbody, thead, and tfoot elementschar on tbody, thead, and tfoot elementscharoff on tbody, thead, and tfoot elementsheight on thead, tbody, and tfoot elementsvalign on tbody, thead, and tfoot elementsalign on td and th elementsbgcolor on td and th elementschar on td and th elementscharoff on td and th elementsheight on td and th elementsnowrap on td and th elementsvalign on td and th elementswidth on td and th elementsalign on tr elementsbgcolor on tr elementschar on tr elementscharoff on tr elementsheight on tr elementsvalign on tr elementscompact on ul elementstype on ul elementsUse CSS instead.
The marquee element is a presentational element that animates content. CSS
transitions and animations are a more appropriate mechanism. [CSSANIMATIONS] [CSSTRANSITIONS]
The marquee element must implement the HTMLMarqueeElement
interface.
When the stop() method is called, the marquee element
must be turned off.
The behavior
content attribute on marquee elements is an enumerated attribute with
the following keywords and states (all non-conforming):
| Keyword | State |
|---|---|
scroll
| |
slide
| |
alternate
|
The attribute's missing value default and invalid value default are both the scroll state.
The direction content attribute on marquee
elements is an enumerated attribute with the following keywords and states (all
non-conforming):
| Keyword | State |
|---|---|
left
| |
right
| |
up
| |
down
|
The attribute's missing value default and invalid value default are both the left state.
The truespeed content attribute on marquee
elements is a boolean attribute.
A marquee element has a marquee scroll distance, which, if the element
has a scrollamount attribute, and
parsing its value using the rules for parsing non-negative integers does not return
an error, is the parsed value interpreted in CSS pixels, and otherwise
is 6 CSS pixels.
A marquee element has a marquee loop count, which, if the element has a
loop attribute, and
parsing its value using the rules for parsing integers does not return an error or a
number less than 1, is the parsed value, and otherwise is −1.
The trueSpeed IDL attribute must reflect the
truespeed content attribute.
The frameset element must implement the HTMLFrameSetElement
interface.
The frameset element exposes as event handler content attributes a
number of the event handlers of the Window object. It also mirrors their
event handler IDL attributes.
The event handlers of the Window object named by the
Window-reflecting body element event handler set, exposed on the
frameset element, replace the generic event handlers with the same names
normally supported by HTML elements.
The frame HTML element insertion steps, given
insertedNode, are:
If insertedNode is not in a document tree, then return.
If insertedNode's root's browsing context is null, then return.
Create a new child navigable for insertedNode.
Process the frame attributes for insertedNode, with
initialInsertion set to true.
The frame HTML element removing steps, given removedNode,
are to destroy a child navigable given removedNode.
Whenever a frame element with a non-null content navigable has its
src attribute set, changed, or removed, the user
agent must process the frame attributes.
To process the frame attributes for an element element, with
an optional boolean initialInsertion:
Let url be the result of running the shared attribute processing steps
for iframe and frame elements given element and
initialInsertion.
If url is null, then return.
If url matches about:blank and
initialInsertion is true, then:
Fire an event named load at element.
Return.
Navigate an iframe or frame given
element, url, and the empty string.
The frame element potentially delays the load event.
The frame element must implement the HTMLFrameElement interface.
The contentWindow getter steps are to return
this's content window.
User agents must treat acronym elements in a manner
equivalent to abbr elements in terms of semantics and
for purposes of rendering.
The coords,
charset, name, rev, and shape IDL attributes of the
a element must reflect the respective content attributes of the same
name.
The noHref IDL
attribute of the area element must reflect the element's nohref content attribute.
The background IDL attribute of the body
element must reflect the element's background
content attribute. (The background content is not
defined to contain a URL, despite rules regarding its handling in the Rendering
section above.)
The clear IDL
attribute of the br element must reflect the content attribute of the
same name.
The align IDL attribute of the caption element
must reflect the content attribute of the same name.
The vAlign
IDL attribute of the col element must reflect the element's valign content attribute.
User agents must treat dir elements in a manner equivalent to ul
elements in terms of semantics and for purposes of rendering.
The dir element must implement the HTMLDirectoryElement
interface.
The compact IDL attribute of the dir element must
reflect the content attribute of the same name.
The align IDL
attribute of the div element must reflect the content attribute of the
same name.
The compact
IDL attribute of the dl element must reflect the content attribute of
the same name.
The name and
align IDL
attributes of the embed element must reflect the respective content
attributes of the same name.
The font element must implement the HTMLFontElement interface.
The color, face, and size IDL attributes of the
font element must reflect the respective content attributes of the same
name.
The align IDL
attribute of the h1–h6 elements must reflect the
content attribute of the same name.
The noShade IDL
attribute of the hr element must reflect the element's noshade content attribute.
The version
IDL attribute of the html element must reflect the content attribute of
the same name.
The marginWidth IDL attribute of the iframe
element must reflect the element's marginwidth content attribute.
The lowsrc IDL
attribute of the img element must reflect the element's lowsrc content attribute, which for the purposes of reflection is
defined as containing a URL.
The useMap
IDL attribute of the input element must reflect the element's usemap content attribute.
The align
IDL attribute of the legend element must reflect the content attribute
of the same name.
The type IDL
attribute of the li element must reflect the content attribute of the
same name.
The charset,
rev, and target IDL attributes
of the link element must reflect the respective content attributes of
the same name.
User agents must treat listing elements in a manner equivalent to pre
elements in terms of semantics and for purposes of rendering.
The compact
IDL attribute of the menu element must reflect the content attribute of
the same name.
User agents may treat the scheme content attribute on the
meta element as an extension of the element's name content attribute when processing a meta element
with a name attribute whose value is one that the user agent
recognizes as supporting the scheme attribute.
User agents are encouraged to ignore the scheme attribute
and instead process the value given to the metadata name as if it had been specified for each
expected value of the scheme attribute.
The scheme IDL
attribute of the meta element must reflect the content attribute of the
same name.
The codeType IDL attribute of the object
element must reflect the element's codetype content attribute.
Support in all current engines.
The useMap
IDL attribute must reflect the usemap
content attribute.
The compact
IDL attribute of the ol element must reflect the content attribute of
the same name.
The align IDL
attribute of the p element must reflect the content attribute of the
same name.
The param element must implement the HTMLParamElement interface.
The valueType IDL attribute of the param
element must reflect the element's valuetype content
attribute.
User agents must treat plaintext elements in a manner equivalent to
pre elements in terms of semantics and for purposes of rendering. (The parser has
special behavior for this element, though.)
The width IDL
attribute of the pre element must reflect the content attribute of the
same name.
The type IDL
attribute of the style element must reflect the element's type content attribute.
The htmlFor IDL attribute of the script element
must reflect the element's for content
attribute.
The cellSpacing IDL attribute of the table
element must reflect the element's cellspacing content attribute.
The vAlign IDL attribute of the tbody,
thead, and tfoot elements must reflect the elements' valign content attributes.
The bgColor IDL attribute of the td and
th elements must reflect the elements' bgcolor content attributes.
The bgColor
IDL attribute of the tr element must reflect the element's bgcolor content attribute.
The compact
and type IDL
attributes of the ul element must reflect the respective content
attributes of the same name.
User agents must treat xmp elements in a manner equivalent to pre
elements in terms of semantics and for purposes of rendering. (The parser has special behavior for
this element though.)
The attributes of the Document object listed in the first column of the following
table must reflect the content attribute on the body element with the
name given in the corresponding cell in the second column on the same row, if the body
element is a body element (as opposed to a frameset element).
When there is no body element or if it is a
frameset element, the attributes must instead return the empty string on getting and
do nothing on setting.
| IDL attribute | Content attribute |
|---|---|
fgColor
| text
|
linkColor
| link
|
vlinkColor
| vlink
|
alinkColor
| alink
|
bgColor
| bgcolor
|
The clear(),
captureEvents(),
and releaseEvents() methods must do nothing.
The all attribute
must return an HTMLAllCollection rooted at the Document node, whose
filter matches all elements.
The external attribute of
the Window interface must return an instance of the External
interface:
The AddSearchProvider() and IsSearchProviderInstalled() methods
must do nothing.
This registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
charsetThe charset parameter may be provided to specify the
document's character encoding, overriding any character encoding declarations in the document other than a Byte Order
Mark (BOM). The parameter's value must be an ASCII case-insensitive match for the
string "utf-8". [ENCODING]
Entire novels have been written about the security considerations that apply to HTML documents. Many are listed in this document, to which the reader is referred for more details. Some general concerns bear mentioning here, however:
HTML is scripted language, and has a large number of APIs (some of which are described in this document). Script can expose the user to potential risks of information leakage, credential leakage, cross-site scripting attacks, cross-site request forgeries, and a host of other problems. While the designs in this specification are intended to be safe if implemented correctly, a full implementation is a massive undertaking and, as with any software, user agents are likely to have security bugs.
Even without scripting, there are specific features in HTML which, for historical reasons,
are required for broad compatibility with legacy content but that expose the user to unfortunate
security problems. In particular, the img element can be used in conjunction with
some other features as a way to effect a port scan from the user's location on the Internet.
This can expose local network topologies that the attacker would otherwise not be able to
determine.
HTML relies on a compartmentalization scheme sometimes known as the same-origin policy. An origin in most cases consists of all the pages served from the same host, on the same port, using the same protocol.
It is critical, therefore, to ensure that any untrusted content that forms part of a site be hosted on a different origin than any sensitive content on that site. Untrusted content can easily spoof any other page on the same origin, read data from that origin, cause scripts in that origin to execute, submit forms to and from that origin even if they are protected from cross-site request forgery attacks by unique tokens, and make use of any third-party resources exposed to or rights granted to that origin.
html" and "htm"
are commonly, but certainly not exclusively, used as the
extension for HTML documents.TEXTFragments used with text/html resources
either refer to the indicated part of the corresponding Document, or
provide state information for in-page scripts.
This registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
boundary (defined in RFC2046) [RFC2046]
multipart/x-mixed-replace
resource can be of any type, including types with non-trivial
security implications such as text/html.
multipart/mixed. [RFC2046]
multipart/x-mixed-replace resource.Fragments used with
multipart/x-mixed-replace resources apply to each body part as defined by the type
used by that body part.
This registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
application/xml [RFC7303]application/xml [RFC7303]application/xml [RFC7303]application/xml [RFC7303]application/xml [RFC7303]application/xhtml+xml type asserts that the
resource is an XML document that likely has a document element from the HTML
namespace. Thus, the relevant specifications are XML, Namespaces in
XML, and this specification. [XML] [XMLNS]application/xml [RFC7303]application/xml [RFC7303]xhtml" and "xht" are sometimes used as
extensions for XML resources that have a document element from the HTML
namespace.TEXTFragments used with
application/xhtml+xml resources have the same semantics as with any
XML MIME type. [RFC7303]
This registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
charsetThe charset parameter may be provided. The parameter's value must be
"utf-8". This parameter serves no purpose; it is only allowed for
compatibility with legacy servers.
If used exclusively in the fashion described in the context of hyperlink auditing, this type introduces no new security concerns.
text/ping resources always consist of the four
bytes 0x50 0x49 0x4E 0x47 (`PING`).ping attribute.Fragments have no meaning with
text/ping resources.
This registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
application/json [JSON]application/json [JSON]application/json [JSON]application/json [JSON]application/microdata+json type asserts that the
resource is a JSON text that consists of an object with a single entry called "items" consisting of an array of entries, each of which consists of an object
with an entry called "id" whose value is a string, an entry called "type" whose value is another string, and an entry called "properties" whose value is an object whose entries each have a value consisting
of an array of either objects or strings, the objects being of the same form as the objects in
the aforementioned "items" entry. Thus, the relevant specifications are
JSON and this specification. [JSON]
Applications that transfer data intended for use with HTML's microdata feature, especially in the context of drag-and-drop, are the primary application class for this type.
application/json [JSON]application/json [JSON]application/json [JSON]Fragments used with
application/microdata+json resources have the same semantics as when used with
application/json (namely, at the time of writing, no semantics at all).
[JSON]
This registration is for community review and will be submitted to the IESG for review, approval, and registration with IANA.
charsetThe charset parameter may be provided. The parameter's value must be
"utf-8". This parameter serves no purpose; it is only allowed for
compatibility with legacy servers.
An event stream from an origin distinct from the origin of the content consuming the event stream can result in information leakage. To avoid this, user agents are required to apply CORS semantics. [FETCH]
Event streams can overwhelm a user agent; a user agent is expected to apply suitable restrictions to avoid depleting local resources because of an overabundance of information from an event stream.
Servers can be overwhelmed if a situation develops in which the server is causing clients to reconnect rapidly. Servers should use a 5xx status code to indicate capacity problems, as this will prevent conforming clients from reconnecting automatically.
Fragments have no meaning with
text/event-stream resources.
This section describes a convention for use with the IANA URI scheme registry. It does not itself register a specific scheme. [RFC7595]
web+" followed by one or more letters in the range
a-z.
web+" schemes should use UTF-8 encodings where relevant.web+" schemes. As
such, these schemes must not be used for features intended to be core platform features (e.g.,
HTTP). Similarly, such schemes must not store confidential information in their URLs, such as
usernames, passwords, personal information, or confidential project names.
The following sections only cover conforming elements and features.
This section is non-normative.
An asterisk (*) in a cell indicates that the actual rules are more complicated than indicated in the table above.
† Categories in the "Parents" column refer to parents that list
the given categories in their content model, not to elements that themselves are in those
categories. For example, the a element's "Parents" column says "phrasing", so any
element whose content model contains the "phrasing" category could be a parent of an
a element. Since the "flow" category includes all the "phrasing" elements, that means
the th element could be a parent to an a element.
This section is non-normative.
This section is non-normative.
| Attribute | Element(s) | Description | Value |
|---|---|---|---|
abbr
| th
| Alternative label to use for the header cell when referencing the cell in other contexts | Text* |
accept
| input
| Hint for expected file type in file upload controls | Set of comma-separated tokens* consisting of valid MIME type strings with no parameters or audio/*, video/*, or image/*
|
accept-charset
| form
| Character encodings to use for form submission | ASCII case-insensitive match for "UTF-8"
|
accesskey
| HTML elements | Keyboard shortcut to activate or focus element | Ordered set of unique space-separated tokens, none of which are identical to another, each consisting of one code point in length |
action
| form
| URL to use for form submission | Valid non-empty URL potentially surrounded by spaces |
allow
| iframe
| Permissions policy to be applied to the iframe's contents
| Serialized permissions policy |
allowfullscreen
| iframe
| Whether to allow the iframe's contents to use requestFullscreen()
| Boolean attribute |
alpha
| input
| Allow the color's alpha component to be set | Boolean attribute |
alt
| area;
img;
input
| Replacement text for use when images are not available | Text* |
as
| link
| Potential destination for a preload request (for rel="preload" and rel="modulepreload")
| Potential destination, for rel="preload"; script-like destination, for rel="modulepreload"
|
async
| script
| Execute script when available, without blocking while fetching | Boolean attribute |
autocapitalize
| HTML elements | Recommended autocapitalization behavior (for supported input methods) | "on";
"off";
"none";
"sentences";
"words";
"characters"
|
autocomplete
| form
| Default setting for autofill feature for controls in the form | "on"; "off"
|
autocomplete
| input;
select;
textarea
| Hint for form autofill feature | Autofill field name and related tokens* |
autocorrect
| HTML elements | Recommended autocorrection behavior (for supported input methods) | "on";
"off"
|
autofocus
| HTML elements | Automatically focus the element when the page is loaded | Boolean attribute |
autoplay
| audio;
video
| Hint that the media resource can be started automatically when the page is loaded | Boolean attribute |
blocking
| link;
script;
style
| Whether the element is potentially render-blocking | Unordered set of unique space-separated tokens* |
charset
| meta
| Character encoding declaration | "utf-8"
|
checked
| input
| Whether the control is checked | Boolean attribute |
cite
| blockquote;
del;
ins;
q
| Link to the source of the quotation or more information about the edit | Valid URL potentially surrounded by spaces |
class
| HTML elements | Classes to which the element belongs | Set of space-separated tokens |
closedby
| dialog
| Which user actions will close the dialog | "any";
"closerequest";
"none";
|
color
| link
| Color to use when customizing a site's icon (for rel="mask-icon")
| CSS <color> |
colorspace
| input
| The color space of the serialized color | "limited-srgb";
"display-p3"
|
cols
| textarea
| Maximum number of characters per line | Valid non-negative integer greater than zero |
colspan
| td;
th
| Number of columns that the cell is to span | Valid non-negative integer greater than zero |
content
| meta
| Value of the element | Text* |
contenteditable
| HTML elements | Whether the element is editable | "true"; "plaintext-only";
"false"
|
controls
| audio;
video
| Show user agent controls | Boolean attribute |
coords
| area
| Coordinates for the shape to be created in an image map | Valid list of floating-point numbers* |
crossorigin
| audio;
img;
link;
script;
video
| How the element handles crossorigin requests | "anonymous"; "use-credentials"
|
data
| object
| Address of the resource | Valid non-empty URL potentially surrounded by spaces |
datetime
| del;
ins
| Date and (optionally) time of the change | Valid date string with optional time |
datetime
| time
| Machine-readable value | Valid month string, valid date string, valid yearless date string, valid time string, valid local date and time string, valid time-zone offset string, valid global date and time string, valid week string, valid non-negative integer, or valid duration string |
decoding
| img
| Decoding hint to use when processing this image for presentation | "sync";
"async";
"auto"
|
default
| track
| Enable the track if no other text track is more suitable | Boolean attribute |
defer
| script
| Defer script execution | Boolean attribute |
dir
| HTML elements | The text directionality of the element | "ltr"; "rtl"; "auto"
|
dir
| bdo
| The text directionality of the element | "ltr"; "rtl"
|
dirname
| input;
textarea
| Name of form control to use for sending the element's directionality in form submission | Text* |
disabled
| button;
input;
optgroup;
option;
select;
textarea;
form-associated custom elements
| Whether the form control is disabled | Boolean attribute |
disabled
| fieldset
| Whether the descendant form controls, except any inside legend, are disabled
| Boolean attribute |
disabled
| link
| Whether the link is disabled | Boolean attribute |
download
| a;
area
| Whether to download the resource instead of navigating to it, and its filename if so | Text |
draggable
| HTML elements | Whether the element is draggable | "true"; "false"
|
enctype
| form
| Entry list encoding type to use for form submission | "application/x-www-form-urlencoded"; "multipart/form-data"; "text/plain"
|
enterkeyhint
| HTML elements | Hint for selecting an enter key action | "enter";
"done";
"go";
"next";
"previous";
"search";
"send"
|
fetchpriority
| img;
link;
script
| Sets the priority for fetches initiated by the element | "auto";
"high";
"low"
|
for
| label
| Associate the label with form control | ID* |
for
| output
| Specifies controls from which the output was calculated | Unordered set of unique space-separated tokens consisting of IDs* |
form
| button;
fieldset;
input;
object;
output;
select;
textarea;
form-associated custom elements
| Associates the element with a form element
| ID* |
formaction
| button;
input
| URL to use for form submission | Valid non-empty URL potentially surrounded by spaces |
formenctype
| button;
input
| Entry list encoding type to use for form submission | "application/x-www-form-urlencoded"; "multipart/form-data"; "text/plain"
|
formmethod
| button;
input
| Variant to use for form submission | "GET";
"POST";
"dialog"
|
formnovalidate
| button;
input
| Bypass form control validation for form submission | Boolean attribute |
formtarget
| button;
input
| Navigable for form submission | Valid navigable target name or keyword |
headers
| td;
th
| The header cells for this cell | Unordered set of unique space-separated tokens consisting of IDs* |
height
| canvas;
embed;
iframe;
img;
input;
object;
source (in picture);
video
| Vertical dimension | Valid non-negative integer |
hidden
| Whether the element is relevant | ""; ""; the empty string | |
high
| meter
| Low limit of high range | Valid floating-point number* |
href
| a;
area
| Address of the hyperlink | Valid URL potentially surrounded by spaces |
href
| link
| Address of the hyperlink | Valid non-empty URL potentially surrounded by spaces |
href
| base
| Document base URL | Valid URL potentially surrounded by spaces |
hreflang
| a;
link
| Language of the linked resource | Valid BCP 47 language tag |
http-equiv
| meta
| Pragma directive | "content-type";
"default-style";
"refresh";
"x-ua-compatible";
"content-security-policy"
|
id
| HTML elements | The element's ID | Text* |
imagesizes
| link
| Image sizes for different page layouts (for rel="preload")
| Valid source size list |
imagesrcset
| link
| Images to use in different situations, e.g., high-resolution displays, small monitors, etc. (for rel="preload")
| Comma-separated list of image candidate strings |
inert
| HTML elements | Whether the element is inert. | Boolean attribute |
inputmode
| HTML elements | Hint for selecting an input modality | "none";
"text";
"tel";
"email";
"url";
"numeric";
"decimal";
"search"
|
integrity
| link;
script
| Integrity metadata used in Subresource Integrity checks [SRI] | Text |
is
| HTML elements | Creates a customized built-in element | Valid custom element name of a defined customized built-in element |
ismap
| img
| Whether the image is a server-side image map | Boolean attribute |
itemid
| HTML elements | Global identifier for a microdata item | Valid URL potentially surrounded by spaces |
itemprop
| HTML elements | Property names of a microdata item | Unordered set of unique space-separated tokens consisting of valid absolute URLs, defined property names, or text* |
itemref
| HTML elements | Referenced elements | Unordered set of unique space-separated tokens consisting of IDs* |
itemscope
| HTML elements | Introduces a microdata item | Boolean attribute |
itemtype
| HTML elements | Item types of a microdata item | Unordered set of unique space-separated tokens consisting of valid absolute URLs* |
kind
| track
| The type of text track | "subtitles";
"captions";
"descriptions";
"chapters";
"metadata"
|
label
| optgroup;
option;
track
| User-visible label | Text |
lang
| HTML elements | Language of the element | Valid BCP 47 language tag or the empty string |
list
| input
| List of autocomplete options | ID* |
loading
| iframe;
img
| Used when determining loading deferral | "lazy";
"eager"
|
loop
| audio;
video
| Whether to loop the media resource | Boolean attribute |
low
| meter
| High limit of low range | Valid floating-point number* |
max
| input
| Maximum value | Varies* |
max
| meter;
progress
| Upper bound of range | Valid floating-point number* |
maxlength
| input;
textarea
| Maximum length of value | Valid non-negative integer |
media
| link;
meta;
source;
style
| Applicable media | Valid media query list |
method
| form
| Variant to use for form submission | "GET";
"POST";
"dialog"
|
min
| input
| Minimum value | Varies* |
min
| meter
| Lower bound of range | Valid floating-point number* |
minlength
| input;
textarea
| Minimum length of value | Valid non-negative integer |
multiple
| input;
select
| Whether to allow multiple values | Boolean attribute |
muted
| audio;
video
| Whether to mute the media resource by default | Boolean attribute |
name
| button;
fieldset;
input;
output;
select;
textarea;
form-associated custom elements
| Name of the element to use for form submission and in the form.elements API
| Text* |
name
| details
| Name of group of mutually-exclusive details elements
| Text* |
name
| form
| Name of form to use in the document.forms API
| Text* |
name
| iframe;
object
| Name of content navigable | Valid navigable target name or keyword |
name
| map
| Name of image map to reference from the usemap attribute
| Text* |
name
| meta
| Metadata name | Text* |
name
| slot
| Name of shadow tree slot | Text |
nomodule
| script
| Prevents execution in user agents that support module scripts | Boolean attribute |
nonce
| HTML elements | Cryptographic nonce used in Content Security Policy checks [CSP] | Text |
novalidate
| form
| Bypass form control validation for form submission | Boolean attribute |
open
| details
| Whether the details are visible | Boolean attribute |
open
| dialog
| Whether the dialog box is showing | Boolean attribute |
optimum
| meter
| Optimum value in gauge | Valid floating-point number* |
pattern
| input
| Pattern to be matched by the form control's value | Regular expression matching the JavaScript Pattern production |
ping
| a;
area
| URLs to ping | Set of space-separated tokens consisting of valid non-empty URLs |
placeholder
| input;
textarea
| User-visible label to be placed within the form control | Text* |
playsinline
| video
| Encourage the user agent to display video content within the element's playback area | Boolean attribute |
popover
| HTML elements | Makes the element a popover element | "auto";
"manual";
|
popovertarget
| button;
input
| Targets a popover element to toggle, show, or hide | ID* |
popovertargetaction
| button;
input
| Indicates whether a targeted popover element is to be toggled, shown, or hidden | "toggle";
"show";
"hide"
|
poster
| video
| Poster frame to show prior to video playback | Valid non-empty URL potentially surrounded by spaces |
preload
| audio;
video
| Hints how much buffering the media resource will likely need | "none";
"metadata";
"auto"
|
readonly
| input;
textarea
| Whether to allow the value to be edited by the user | Boolean attribute |
readonly
| form-associated custom elements | Affects willValidate, plus any behavior added by the custom element author
| Boolean attribute |
referrerpolicy
| a;
area;
iframe;
img;
link;
script
| Referrer policy for fetches initiated by the element | Referrer policy |
rel
| a;
area
| Relationship between the location in the document containing the hyperlink and the destination resource | Unordered set of unique space-separated tokens* |
rel
| link
| Relationship between the document containing the hyperlink and the destination resource | Unordered set of unique space-separated tokens* |
required
| input;
select;
textarea
| Whether the control is required for form submission | Boolean attribute |
reversed
| ol
| Number the list backwards | Boolean attribute |
rows
| textarea
| Number of lines to show | Valid non-negative integer greater than zero |
rowspan
| td;
th
| Number of rows that the cell is to span | Valid non-negative integer |
sandbox
| iframe
| Security rules for nested content | Unordered set of unique space-separated tokens, ASCII case-insensitive, consisting of |
scope
| th
| Specifies which cells the header cell applies to | "row";
"col";
"rowgroup";
"colgroup"
|
selected
| option
| Whether the option is selected by default | Boolean attribute |
shadowrootclonable
| template
| Sets clonable on a declarative shadow root | Boolean attribute |
shadowrootdelegatesfocus
| template
| Sets delegates focus on a declarative shadow root | Boolean attribute |
shadowrootmode
| template
| Enables streaming declarative shadow roots | "open";
"closed"
|
shadowrootserializable
| template
| Sets serializable on a declarative shadow root | Boolean attribute |
shape
| area
| The kind of shape to be created in an image map | "circle";
"default";
"poly";
"rect"
|
size
| input;
select
| Size of the control | Valid non-negative integer greater than zero |
sizes
| link
| Sizes of the icons (for rel="icon")
| Unordered set of unique space-separated tokens, ASCII case-insensitive, consisting of sizes* |
sizes
| img;
source
| Image sizes for different page layouts | Valid source size list |
slot
| HTML elements | The element's desired slot | Text |
span
| col;
colgroup
| Number of columns spanned by the element | Valid non-negative integer greater than zero |
spellcheck
| HTML elements | Whether the element is to have its spelling and grammar checked | "true";
"false";
the empty string
|
src
| audio;
embed;
iframe;
img;
input;
script;
source (in video or audio);
track;
video
| Address of the resource | Valid non-empty URL potentially surrounded by spaces |
srcdoc
| iframe
| A document to render in the iframe
| The source of an iframe srcdoc document*
|
srclang
| track
| Language of the text track | Valid BCP 47 language tag |
srcset
| img;
source
| Images to use in different situations, e.g., high-resolution displays, small monitors, etc. | Comma-separated list of image candidate strings |
start
| ol
| Starting value of the list | Valid integer |
step
| input
| Granularity to be matched by the form control's value | Valid floating-point number greater than zero, or "any"
|
style
| HTML elements | Presentational and formatting instructions | CSS declarations* |
tabindex
| HTML elements | Whether the element is focusable and sequentially focusable, and the relative order of the element for the purposes of sequential focus navigation | Valid integer |
target
| a;
area
| Navigable for hyperlink navigation | Valid navigable target name or keyword |
target
| base
| Default navigable for hyperlink navigation and form submission | Valid navigable target name or keyword |
target
| form
| Navigable for form submission | Valid navigable target name or keyword |
title
| HTML elements | Advisory information for the element | Text |
title
| abbr;
dfn
| Full term or expansion of abbreviation | Text |
title
| input
| Description of pattern (when used with pattern attribute)
| Text |
title
| link
| Title of the link | Text |
title
| link;
style
| CSS style sheet set name | Text |
translate
| HTML elements | Whether the element is to be translated when the page is localized | "yes"; "no"
|
type
| a;
link
| Hint for the type of the referenced resource | Valid MIME type string |
type
| button
| Type of button | "submit";
"reset";
"button"
|
type
| embed;
object;
source
| Type of embedded resource | Valid MIME type string |
type
| input
| Type of form control | input type keyword
|
type
| ol
| Kind of list marker | "1";
"a";
"A";
"i";
"I"
|
type
| script
| Type of script | "module"; a valid MIME type string that is not a JavaScript MIME type essence match
|
usemap
| img
| Name of image map to use | Valid hash-name reference* |
value
| button;
option
| Value to be used for form submission | Text |
value
| data
| Machine-readable value | Text* |
value
| input
| Value of the form control | Varies* |
value
| li
| Ordinal value of the list item | Valid integer |
value
| meter;
progress
| Current value of the element | Valid floating-point number |
width
| canvas;
embed;
iframe;
img;
input;
object;
source (in picture);
video
| Horizontal dimension | Valid non-negative integer |
wrap
| textarea
| How the value of the form control is to be wrapped for form submission | "soft";
"hard"
|
writingsuggestions
| HTML elements | Whether the element can offer writing suggestions or not. | "true";
"false";
the empty string
|
An asterisk (*) in a cell indicates that the actual rules are more complicated than indicated in the table above.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
Support in all current engines.
This section is non-normative.
This section is non-normative.
AudioTrackAudioTrackListBarPropBeforeUnloadEventBroadcastChannelCanvasGradientCanvasPatternCanvasRenderingContext2DCloseWatcherCustomElementRegistryCustomStateSetDOMParserDOMStringListDOMStringMapDataTransferDataTransferItemDataTransferItemListDedicatedWorkerGlobalScopeDocument, partial 1 2DragEventElement, partialElementInternalsErrorEventEventSourceExternalFormDataEventHTMLAllCollectionHTMLAnchorElement, partialHTMLAreaElement, partialHTMLAudioElementHTMLBRElement, partialHTMLBaseElementHTMLBodyElement, partialHTMLButtonElementHTMLCanvasElementHTMLDListElement, partialHTMLDataElementHTMLDataListElementHTMLDetailsElementHTMLDialogElementHTMLDirectoryElementHTMLDivElement, partialHTMLElementHTMLEmbedElement, partialHTMLFieldSetElementHTMLFontElementHTMLFormControlsCollectionHTMLFormElementHTMLFrameElementHTMLFrameSetElementHTMLHRElement, partialHTMLHeadElementHTMLHeadingElement, partialHTMLHtmlElement, partialHTMLIFrameElement, partialHTMLImageElement, partialHTMLInputElement, partialHTMLLIElement, partialHTMLLabelElementHTMLLegendElement, partialHTMLLinkElement, partialHTMLMapElementHTMLMarqueeElementHTMLMediaElementHTMLMenuElement, partialHTMLMetaElement, partialHTMLMeterElementHTMLModElementHTMLOListElement, partialHTMLObjectElement, partialHTMLOptGroupElementHTMLOptionElementHTMLOptionsCollectionHTMLOutputElementHTMLParagraphElement, partialHTMLParamElementHTMLPictureElementHTMLPreElement, partialHTMLProgressElementHTMLQuoteElementHTMLScriptElement, partialHTMLSelectElementHTMLSlotElementHTMLSourceElementHTMLSpanElementHTMLStyleElement, partialHTMLTableCaptionElement, partialHTMLTableCellElement, partialHTMLTableColElement, partialHTMLTableElement, partialHTMLTableRowElement, partialHTMLTableSectionElement, partialHTMLTemplateElementHTMLTextAreaElementHTMLTimeElementHTMLTitleElementHTMLTrackElementHTMLUListElement, partialHTMLUnknownElementHTMLVideoElementHashChangeEventHistoryImageBitmapImageBitmapRenderingContextImageDataLocationMediaErrorMessageChannelMessageEventMessagePortMimeTypeMimeTypeArrayNavigateEventNavigationNavigationActivationNavigationCurrentEntryChangeEventNavigationDestinationNavigationHistoryEntryNavigationTransitionNavigator, partialNotRestoredReasonDetailsNotRestoredReasonsOffscreenCanvasOffscreenCanvasRenderingContext2DPageRevealEventPageSwapEventPageTransitionEventPath2DPluginPluginArrayPopStateEventPromiseRejectionEventRadioNodeListRange, partialShadowRoot, partialSharedWorkerSharedWorkerGlobalScopeStorageStorageEventSubmitEventTextMetricsTextTrackTextTrackCueTextTrackCueListTextTrackListTimeRangesToggleEventTrackEventUserActivationValidityStateVideoTrackVideoTrackListVisibilityStateEntryWindow, partialWorkerWorkerGlobalScopeWorkerLocationWorkerNavigatorWorkletWorkletGlobalScopeThis section is non-normative.
The following table lists events fired by this document, excluding those already defined in media element events and drag-and-drop events.
| Event | Interface | Interesting targets | Description |
|---|---|---|---|
DOMContentLoaded
Support in all current engines. Firefox1+Safari3.1+Chrome1+ Opera9+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android10.1+ | Event
| Document
| Fired at the Document once the parser has finished
|
afterprint
Support in all current engines. Firefox6+Safari13+Chrome63+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| Window
| Fired at the Window after printing
|
beforeprint
Support in all current engines. Firefox6+Safari13+Chrome63+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| Window
| Fired at the Window before printing
|
beforematch
Support in one engine only. FirefoxNoSafariNoChrome102+ OperaNoEdge102+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| Elements | Fired on elements with the attribute before they are revealed. |
beforetoggle
HTMLElement/beforetoggle_event Support in all current engines. Firefox🔰 114+Safaripreview+Chrome114+ Opera?Edge114+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | ToggleEvent
| Elements | Fired on elements with the popover attribute when they
are transitioning between showing and hidden
|
beforeunload
Support in all current engines. Firefox1+Safari3+Chrome1+ Opera12+Edge79+ Edge (Legacy)12+Internet Explorer4+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | BeforeUnloadEvent
| Window
| Fired at the Window when the page is about to be unloaded, in case the page would like to show a warning prompt
|
blur
| Event
| Window, elements
| Fired at nodes when they stop being focused |
cancel
HTMLDialogElement/cancel_event Support in all current engines. Firefox98+Safari15.4+Chrome37+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome AndroidNoWebView Android?Samsung Internet?Opera Android? | Event
| CloseWatcher, dialog elements, input elements
| Fired at CloseWatcher objects or dialog elements when they receive a close request, or at input elements in the File state when the user does not change their selection
|
change
Support in all current engines. Firefox1+Safari3+Chrome1+ Opera9+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | Event
| Form controls | Fired at controls when the user commits a value change (see also the input event)
|
click
| PointerEvent
| Elements | Normally a mouse event; also synthetically fired at an element before its activation behavior is run, when an element is activated from a non-pointer input device (e.g. a keyboard) |
close
Support in all current engines. Firefox98+Safari15.4+Chrome37+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| CloseWatcher, dialog elements, MessagePort
| Fired at CloseWatcher objects or dialog elements when they are closed via a close request or via web developer code, or at MessagePort objects when disentangled
|
connect
SharedWorkerGlobalScope/connect_event Support in all current engines. Firefox29+Safari16+Chrome4+ Opera10.6+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS16+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | MessageEvent
| SharedWorkerGlobalScope
| Fired at a shared worker's global scope when a new client connects |
contextlost
HTMLCanvasElement/webglcontextlost_event Support in one engine only. FirefoxNoSafariNoChrome98+ Opera?Edge98+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| canvas elements, OffscreenCanvas objects
| Fired when the corresponding CanvasRenderingContext2D or OffscreenCanvasRenderingContext2D is lost
|
contextrestored
HTMLCanvasElement/contextrestored_event Support in one engine only. FirefoxNoSafariNoChrome98+ Opera?Edge98+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | Event
| canvas elements, OffscreenCanvas objects
| Fired when the corresponding CanvasRenderingContext2D or OffscreenCanvasRenderingContext2D is restored after being lost
|
currententrychange
| NavigationCurrentEntryChangeEvent
| Navigation
| Fired when navigation.currentEntry changes
|
dispose
| Event
| NavigationHistoryEntry
| Fired when the session history entry corresponding to the NavigationHistoryEntry has been permanently evicted from session history and can no longer be traversed to
|
error
Support in all current engines. Firefox6+Safari5+Chrome6+ Opera12+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ Support in all current engines. Firefox6+Safari5.1+Chrome10+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | Event or ErrorEvent
| Global scope objects, Worker objects, elements, networking-related objects
| Fired when unexpected errors occur (e.g. networking errors, script errors, decoding errors) |
focus
| Event
| Window, elements
| Fired at nodes gaining focus |
formdata
HTMLFormElement/formdata_event Support in all current engines. Firefox72+Safari15+Chrome77+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | FormDataEvent
| form elements
| Fired at a form element when it is constructing the entry list
|
hashchange
Support in all current engines. Firefox3.6+Safari5+Chrome8+ Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer8+ Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android11+ | HashChangeEvent
| Window
| Fired at the Window when the fragment part of the document's URL changes
|
input
| Event
| Elements | Fired when the user changes the contenteditable element's content, or the form control's value. See also the change event for form controls.
|
invalid
HTMLInputElement/invalid_event Support in all current engines. Firefox4+Safari5+Chrome10+ Opera10+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android64+Safari iOS5+Chrome Android?WebView Android4+Samsung Internet4.0+Opera Android12+ | Event
| Form controls | Fired at controls during form validation if they do not satisfy their constraints |
languagechange
Support in all current engines. Firefox32+Safari10.1+Chrome37+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android4+Safari iOS?Chrome Android?WebView Android?Samsung Internet4.0+Opera Android? WorkerGlobalScope/languagechange_event Support in all current engines. Firefox74+Safari4+Chrome4+ Opera11.5+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | Event
| Global scope objects | Fired at the global scope object when the user's preferred languages change |
load
| Event
| Window, elements
| Fired at the Window when the document has finished loading; fired at an element containing a resource (e.g. img, embed) when its resource has finished loading
|
message
BroadcastChannel/message_event Support in all current engines. Firefox38+Safari15.4+Chrome54+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? DedicatedWorkerGlobalScope/message_event Support in all current engines. Firefox3.5+Safari4+Chrome4+ Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS5+Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ Support in all current engines. Firefox6+Safari5+Chrome6+ Opera12+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ Support in all current engines. Firefox41+Safari5+Chrome2+ Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ Support in all current engines. Firefox9+Safari4+Chrome60+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer8+ Firefox Android?Safari iOS4+Chrome Android?WebView Android?Samsung Internet?Opera Android47+ Support in all current engines. Firefox3.5+Safari4+Chrome4+ Opera10.6+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android11.5+ | MessageEvent
| Window, EventSource, MessagePort, BroadcastChannel, DedicatedWorkerGlobalScope, Worker, ServiceWorkerContainer
| Fired at an object when it receives a message |
messageerror
BroadcastChannel/messageerror_event Support in all current engines. Firefox57+Safari15.4+Chrome60+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ DedicatedWorkerGlobalScope/messageerror_event Support in all current engines. Firefox57+Safari16.4+Chrome60+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ MessagePort/messageerror_event Support in all current engines. Firefox57+Safari16.4+Chrome60+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ Support in all current engines. Firefox57+Safari16.4+Chrome60+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ Support in all current engines. Firefox57+Safari16.4+Chrome60+ Opera?Edge79+ Edge (Legacy)18Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+ | MessageEvent
| Window, MessagePort, BroadcastChannel, DedicatedWorkerGlobalScope, Worker, ServiceWorkerContainer
| Fired at an object when it receives a message that cannot be deserialized |
navigate
| NavigateEvent
| Navigation
| Fired before the navigable navigates, reloads, traverses, or otherwise changes its URL |
navigateerror
| ErrorEvent
| Navigation
| Fired when a navigation does not complete successfully |
navigatesuccess
| Event
| Navigation
| Fired when a navigation completes successfully |
offline
Support in all current engines. Firefox9+Safari4+Chrome3+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | Event
| Global scope objects | Fired at the global scope object when the network connections fails |
online
Support in all current engines. Firefox9+Safari4+Chrome3+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS3+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | Event
| Global scope objects | Fired at the global scope object when the network connections returns |
open
Support in all current engines. Firefox6+Safari5+Chrome6+ Opera12+Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android45+Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android12+ | Event
| EventSource
| Fired at EventSource objects when a connection is established
|
pageswap
| PageSwapEvent
| Window
| Fired at the Window right before a document is unloaded as a result of a navigation.
|
pagehide
Support in all current engines. Firefox6+Safari5+Chrome3+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | PageTransitionEvent
| Window
| Fired at the Window when the page's session history entry stops
being the active entry
|
pagereveal
| PageRevealEvent
| Window
| Fired at the Window when the page begins to render for the first time after
it has been initialized or reactivated
|
pageshow
Support in all current engines. Firefox6+Safari5+Chrome3+ Opera?Edge79+ Edge (Legacy)12+Internet Explorer11 Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android? | PageTransitionEvent
| Window
| Fired at the Window when the page's session history entry
becomes the active entry
|
pointercancel
| PointerEvent
| Elements and Text nodes
| Fired at the source node when the user attempts to initiate a drag-and-drop operation |
popstate
Support in all current engines. Firefox4+Safari5+Chrome5+ Opera11.5+Edge79+ Edge (Legacy)12+Internet Explorer10+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+ | PopStateEvent
| Window
| Fired at the Window when in some cases of session history traversal
|
readystatechange
Document/readystatechange_event Support in all current engines. Firefox4+Safari5.1+Chrome9+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer4+ Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | Event
| Document
| Fired at the Document when it finishes parsing and again when all its subresources have finished loading
|
rejectionhandled
| PromiseRejectionEvent
| Global scope objects | Fired at global scope objects when a previously-unhandled promise rejection becomes handled |
reset
Support in all current engines. Firefox6+Safari3+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS1+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+ | Event
| form elements
| Fired at a form element when it is reset
|
select
Support in all current engines. Firefox6+Safari1+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ HTMLTextAreaElement/select_event Support in all current engines. Firefox6+Safari1+Chrome1+ Opera12.1+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+ | Event
| Form controls | Fired at form controls when their text selection is adjusted (whether by an API or by the user) |
storage
Support in all current engines. Firefox45+Safari4+Chrome1+ Opera?Edge79+ Edge (Legacy)15+Internet Explorer9+ Firefox Android?Safari iOS4+Chrome Android?WebView Android37+Samsung Internet?Opera Android? | StorageEvent
| Window
| Fired at Window event when the corresponding localStorage or sessionStorage storage areas change
|
submit
Support in all current engines. Firefox1+Safari3+Chrome1+ Opera8+Edge79+ Edge (Legacy)12+Internet Explorer9+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | SubmitEvent
| form elements
| Fired at a form element when it is submitted
|
toggle
HTMLDetailsElement/toggle_event Support in all current engines. Firefox49+Safari10.1+Chrome36+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? Support in all current engines. Firefox🔰 114+Safaripreview+Chrome114+ Opera?Edge114+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android? | ToggleEvent
| details and popover elements
| Fired at details elements when they open or close; fired on elements with the
popover attribute when they are transitioning between
showing and hidden
|
unhandledrejection
Window/unhandledrejection_event Support in all current engines. Firefox69+Safari11+Chrome49+ Opera?Edge79+ Edge (Legacy)?Internet ExplorerNo Firefox Android?Safari iOS11.3+Chrome Android?WebView Android?Samsung Internet?Opera Android? | PromiseRejectionEvent
| Global scope objects | Fired at global scope objects when a promise rejection goes unhandled |
unload
Support in all current engines. Firefox1+Safari3+Chrome1+ Opera4+Edge79+ Edge (Legacy)12+Internet Explorer4+ Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+ | Event
| Window
| Fired at the Window object when the page is going away
|
visibilitychange
Document/visibilitychange_event Support in all current engines. Firefox56+Safari14.1+Chrome62+ Opera49+Edge79+ Edge (Legacy)18Internet Explorer🔰 10+ Firefox Android?Safari iOS?Chrome Android?WebView Android62+Samsung Internet?Opera Android46+ | Event
| Document
| Fired at the Document object when the page becomes visible or hidden to the
user
|
This section is non-normative.
The following HTTP request headers are defined by this specification:
The following HTTP response headers are defined by this specification:
Cross-Origin-Embedder-Policy`Cross-Origin-Embedder-Policy-Report-Only`Cross-Origin-Opener-Policy`Cross-Origin-Opener-Policy-Report-Only`Origin-Agent-Cluster`Refresh`X-Frame-Options`This section is non-normative.
The following MIME types are mentioned in this specification:
application/atom+xmlapplication/jsonapplication/octet-streamapplication/microdata+jsonapplication/rss+xmlapplication/wasmapplication/x-www-form-urlencodedapplication/xhtml+xmlapplication/xmlimage/gifimage/jpegimage/pngimage/svg+xmlmultipart/form-datamultipart/mixedmultipart/x-mixed-replacetext/csstext/event-streamtext/javascripttext/jsontext/plaintext/htmltext/pingtext/uri-listtext/vcardtext/vtttext/xmlvideo/mp4video/mpegAll references are normative unless marked "Non-normative".
XMLHttpRequest, A. van Kesteren. WHATWG.Thanks to Tim Berners-Lee for inventing HTML, without which none of this would exist.
Thanks to Aankhen, Aaqa Ishtyaq, Aaron Boodman, Aaron Leventhal, Aaron Krajeski, Abhishek Ghaskata, Abhishek Gupta, Adam Barth, Adam de Boor, Adam Hepton, Adam Klein, Adam Rice, Adam Roben, Addison Phillips, Adele Peterson, Adrian Bateman, Adrian Roselli, Adrian Sutton, Agustín Fernández, Aharon (Vladimir) Lanin, Ajai Tirumali, Ajay Poshak, Akash Balenalli, Akatsuki Kitamura, Alan Jeffrey, Alan Plum, Alastair Campbell, Alejandro G. Castro, Alex Bishop, Alex Nicolaou, Alex Nozdriukhin, Alex Rousskov, Alex Soncodi, Alexander Farkas, Alexander J. Vincent, Alexander Kalenik, Alexandre Dieulot, Alexandre Morgaut, Alexey Feldgendler, Алексей Проскуряков (Alexey Proskuryakov), Alexey Shvayka, Alexis Deveria, Alfred Agrell, Ali Juma, Alice Boxhall, Alice Wonder, Allan Clements, Allen Wirfs-Brock, Alex Komoroske, Alex Russell, Alphan Chen, Aman Ansari, Ami Fischman, Amos Jeffries, Amos Lim, Anders Carlsson, André Bargull, André E. Veltstra, Andrea Rendine, Andreas, Andreas Deuschlinger, Andreas Farre, Andreas Kling, Andrei Popescu, Andres Gomez, Andres Rios, Andreu Botella, Andrew Barfield, Andrew Clover, Andrew Gove, Andrew Grieve, Andrew Kaster, Andrew Macpherson, Andrew Oakley, Andrew Paseltiner, Andrew Simons, Andrew Smith, Andrew W. Hagen, Andrew Williams, Andrey V. Lukyanov, Andry Rendy, Andy Davies, Andy Earnshaw, Andy Heydon, Andy Paicu, Andy Palay, Anjana Vakil, Ankur Kaushal, Anna Belle Leiserson, Anna Sidwell, Anthony Boyd, Anthony Bryan, Anthony Hickson, Anthony Ramine, Anthony Ricaud, Anton Vayvod, Antonio Sartori, Antti Koivisto, Arfat Salman, Arkadiusz Michalski, Arne Thomassen, Aron Spohr, Arphen Lin, Arthur Hemery, Arthur Sonzogni, Arthur Stolyar, Arun Patole, Aryeh Gregor, Asanka Herath, Asbjørn Ulsberg, Ashley Gullen, Ashley Sheridan, Asumu Takikawa, Atsushi Takayama, Attila Haraszti, Aurelien Levy, Ave Wrigley, Avi Drissman, Axel Dahmen, 방성범 (Bang Seongbeom), Barry Pollard, Ben Boyle, Ben Godfrey, Ben Golightly, Ben Kelly, Ben Lerner, Ben Leslie, Ben Meadowcroft, Ben Millard, Benjamin Carl Wiley Sittler, Benjamin Hawkes-Lewis, Benji Bilheimer, Benoit Ren, Bert Bos, Bijan Parsia, Bil Corry, Bill Mason, Bill McCoy, Billy Wong, Billy Woods, Bjartur Thorlacius, Björn Höhrmann, Blake Frantz, Bob Lund, Bob Owen, Bobby Holley, Boris Zbarsky, Brad Fults, Brad Neuberg, Brad Spencer, Bradley Meck, Brady Eidson, Brandon Jones, Brendan Eich, Brenton Simpson, Brett Wilson, Brett Zamir, Brian Birtles, Brian Blakely, Brian Campbell, Brian Korver, Brian Kuhn, Brian M. Dube, Brian Ryner, Brian Smith, Brian Wilson, Bryan Sullivan, Bruce Bailey, Bruce D'Arcus, Bruce Lawson, Bruce Miller, Bugs Nash, C. Scott Ananian, C. Williams, Cameron McCormack, Cameron Zemek, Cao Yipeng, Carlos Amengual, Carlos Gabriel Cardona, Carlos Ibarra López, Carlos Perelló Marín, Carolyn MacLeod, Casey Leask, Cătălin Badea, Cătălin Mariș, Cem Turesoy, ceving, Chao Cai, 윤석찬 (Channy Yun), Charl van Niekerk, Charlene Wright, Charles Iliya Krempeaux, Charles McCathie Nevile, Charlie Reis, 白丞祐 (Cheng-You Bai), Chris Apers, Chris Cressman, Chris Dumez, Chris Evans, Chris Harrelson, Chris Markiewicz, Chris Morris, Chris Nardi, Chris Needham, Chris Pearce, Chris Peterson, Chris Rebert, Chris Weber, Chris Wilson, Christian Biesinger, Christian Johansen, Christian Schmidt, Christoph Päper, Christophe Dumez, Christopher Aillon, Christopher Cameron, Christopher Ferris, Chriswa, Clark Buehler, Cole Robison, Colin Fine, Collin Jackson, Corey Farwell, Corprew Reed, Craig Cockburn, Csaba Gabor, Csaba Marton, Cynthia Shelly, Cyrille Tuzi, Daksh Shah, Dan Callahan, Dan Yoder, Dane Foster, Daniel Barclay, Daniel Bratell, Daniel Brooks, Daniel Brumbaugh Keeney, Daniel Buchner, Daniel Cheng, Daniel Clark, Daniel Davis, Daniel Ehrenberg, Daniel Ethridge, Daniel Glazman, Daniel Holbert, Daniel Peng, Daniel Schattenkirchner, Daniel Spång, Daniel Steinberg, Daniel Tan, Daniel Trebbien, Daniel Vogelheim, Danny Sullivan, Daphne Preston-Kendal, Darien Maillet Valentine, Darin Adler, Darin Fisher, Darxus, Dave Camp, Dave Cramer, Dave Hodder, Dave Lampton, Dave Singer, Dave Tapuska, Dave Townsend, David Baron, David Bloom, David Bokan, David Bruant, David Carlisle, David E. Cleary, David Egan Evans, David Fink, David Flanagan, David Gerard, David Grogan, David Hale, David Håsäther, David Hyatt, David I. Lehn, David John Burrowes, David Matja, David Remahl, David Resseguie, David Smith, David Storey, David Vest, David Woolley, David Zbarsky, Dave Methvin, DeWitt Clinton, Dean Edridge, Dean Edwards, Dean Jackson, Debanjana Sarkar, Debi Orton, Delan Azabani, Derek Featherstone, Derek Guenther, Devarshi Pant, Devdatta, Devin Mullins, Devin Rousso, Di Zhang, Diego Ferreiro Val, Diego González Zúñiga, Diego Ponce de León, Dimitri Glazkov, Dimitry Golubovsky, Dirk Pranke, Dirk Schulze, Dirkjan Ochtman, Divya Manian, Dmitry Lazutkin, Dmitry Titov, dolphinling, Dominic Cooney, Dominique Hazaël-Massieux, Don Brutzman, Donovan Glover, Doron Rosenberg, Doug Kramer, Doug Simpkinson, Drew Wilson, Edgar Chen, Edmund Lai, Eduard Pascual, Eduardo Vela, Edward Welbourne, Edward Z. Yang, Ehsan Akhgari, Eira Monstad, Eitan Adler, Eli Friedman, Eli Grey, Eliot Graff, Elisabeth Robson, Elizabeth Castro, Elliott Sprehn, Elliotte Harold, Emilio Cobos Álvarez, Emily Stark, Eric Carlson, Eric Casler, Eric Lawrence, Eric Portis, Eric Rescorla, Eric Semling, Eric Shepherd, Eric Willigers, Erik Arvidsson, Erik Charlebois, Erik Rose, 栗本 英理子 (Eriko Kurimoto), espretto, Evan Jacobs, Evan Martin, Evan Prodromou, Evan Stade, Evert, Evgeny Kapun, ExE-Boss, Ezequiel Garzón, fantasai, Félix Sanz, Felix Sasaki, Fernando Altomare Serboncini, Forbes Lindesay, Francesco Schwarz, Francis Brosnan Blazquez, Franck 'Shift' Quélain, François Marier, Frank Barchard, Frank Liberato, Franklin Shirley, Frederik Braun, Fredrik Söderquist, 鵜飼文敏 (Fumitoshi Ukai), Futomi Hatano, Gavin Carothers, Gavin Kistner, Gareth Rees, Garrett Smith, Gary Blackwood, Gary Kacmarcik, Gary Katsevman, Geoff Richards, Geoffrey Garen, Georg Neis, George Lund, Gianmarco Armellin, Giovanni Campagna, Giuseppe Pascale, Glenn Adams, Glenn Maynard, Graham Klyne, Greg Botten, Greg Houston, Greg Wilkins, Gregg Tavares, Gregory J. Rosmaita, Gregory Terzian, Grey, guest271314, Guilherme Johansson Tramontina, Guy Bedford, Gytis Jakutonis, Håkon Wium Lie, Habib Virji, Hajime Morrita, Hallvord Reiar Michaelsen Steen, Hanna Laakso, Hans S. Tømmerhalt, Hans Stimer, Harald Alvestrand, Hayato Ito, 何志翔 (HE Zhixiang), Henri Sivonen, Henrik Lied, Henrik Lievonen, Henry Lewis, Henry Mason, Henry Story, Hermann Donfack Zeufack, 中川博貴 (Hiroki Nakagawa), Hiroshige Hayashizaki, Hiroyuki USHITO, Hitoshi Yoshida, Hongchan Choi, 王华 (Hua Wang), Hugh Bellamy, Hugh Guiney, Hugh Winkler, Ian Bicking, Ian Clelland, Ian Davis, Ian Fette, Ian Henderson, Ian Kilpatrick, Ibrahim Ahmed, Ido Green, Ignacio Javier, Igor Oliveira, 安次嶺 一功 (Ikko Ashimine), Ilya Grigorik, Ingvar Stepanyan, isonmad, Iurii Kucherov, Ivan Enderlin, Ivan Nikulin, Ivan Panchenko, Ivo Emanuel Gonçalves, J. King, J.C. Jones, Jackson Ray Hamilton, Jacob Davies, Jacques Distler, Jake Archibald, Jake Verbaten, Jakub Vrána, Jakub Łopuszański, Jakub Wilk, James Craig, James Graham, James Greene, James Justin Harrell, James Kozianski, James M Snell, James Perrett, James Robinson, Jamie Liu, Jamie Lokier, Jamie Mansfield, Jan Kühle, Jan Miksovsky, Janice Shiu, Janusz Majnert, Jan-Ivar Bruaroey, Jan-Klaas Kollhof, Jared Jacobs, Jason Duell, Jason Kersey, Jason Lustig, Jason Orendorff, Jason White, Jasper Bryant-Greene, Jasper St. Pierre, Jatinder Mann, Jay Henry Kao, Jean-Yves Avenard, Jed Hartman, Jeff Balogh, Jeff Cutsinger, Jeff Gilbert, Jeff "=JeffH" Hodges, Jeff Schiller, Jeff Walden, Jeffrey Yasskin, Jeffrey Zeldman, 胡慧鋒 (Jennifer Braithwaite), Jellybean Stonerfish, Jennifer Apacible, Jens Bannmann, Jens Fendler, Jens Oliver Meiert, Jens Widell, Jer Noble, Jeremey Hustman, Jeremy Keith, Jeremy Orlow, Jeremy Roman, Jeroen van der Meer, Jerry Smith, Jesse Renée Beach, Jessica Jong, jfkthame, Jian Li, Jihye Hong, Jim Jewett, Jim Ley, Jim Meehan, Jim Michaels, Jinho Bang, Jinjiang (勾三股四), Jirka Kosek, Jjgod Jiang, Joaquim Medeiros, João Eiras, Jochen Eisinger, Joe Clark, Joe Gregorio, Joel Spolsky, Joel Verhagen, Joey Arhar, Johan Herland, Johanna Herman, John Boyer, John Bussjaeger, John Carpenter, John Daggett, John Fallows, John Foliot, John Harding, John Keiser, John Law, John Musgrave, John Snyders, John Stockton, John-Mark Bell, Johnny Stenback, Jon Coppeard, Jon Ferraiolo, Jon Gibbins, Jon Jensen, Jon Perlow, Jonas Sicking, Jonathan Cook, Jonathan Kew, Jonathan Neal, Jonathan Oddy, Jonathan Rees, Jonathan Watt, Jonathan Worent, Jonny Axelsson, Joram Schrijver, Jordan Tucker, Jorgen Horstink, Joris van der Wel, Jorunn Danielsen Newth, Joseph Kesselman, Joseph Mansfield, Joseph Pecoraro, Josh Aas, Josh Hart, Josh Juran, Josh Levenberg, Josh Matthews, Joshua Bell, Joshua Chen, Joshua Randall, Juan Olvera, Juanmi Huertas, Jukka K. Korpela, Jules Clément-Ripoche, Julian Reschke, Julio Lopez, 小勝 純 (Jun Kokatsu), Jun Yang (harttle), Jungkee Song, Jürgen Jeka, Justin Lebar, Justin Novosad, Justin Rogers, Justin Schuh, Justin Sinclair, Juuso Lapinlampi, Ka-Sing Chou, Kagami Sascha Rosylight, Kai Hendry, Kamishetty Sreeja, 呂康豪 (KangHao Lu), Karl Dubost, Karl Tomlinson, Kartik Arora, Kartikaya Gupta, Kathy Walton, 河童エクマ(Kawarabe Ecma) Keith Cirkel, Keith Rollin, Keith Yeung, Kelly Ford, Kelly Norton, Ken Russell, Kenji Baheux, Kevin Benson, Kevin Cole, Kevin Gadd, Kevin McNee, Kevin Venkiteswaran, Khushal Sagar, Kinuko Yasuda, Koji Ishii, Kornél Pál, Kornel Lesinski, 上野 康平 (UENO, Kouhei), Kris Northfield, Kristian Spangsege, Kristof Zelechovski, Krzysztof Maczyński, 黒澤剛志 (Kurosawa Takeshi), Kyle Barnhart, Kyle Hofmann, Kyle Huey, Léonard Bouchet, Léonie Watson, Lachlan Hunt, Larry Masinter, Larry Page, Lars Gunther, Lars Solberg, Laura Carlson, Laura Granka, Laura L. Carlson, Laura Wisewell, Laurens Holst, Lawrence Forooghian, Lee Kowalkowski, Leif Halvard Silli, Leif Kornstaedt, Lenny Domnitser, Leonard Rosenthol, Leons Petrazickis, Liviu Tinta, Lobotom Dysmon, Logan, Logan Moore, Loune, Lucas Gadani, Łukasz Pilorz, Luke Kenneth Casson Leighton, Luke Warlow, Luke Wilde, Maciej Stachowiak, Magne Andersson, Magnus Kristiansen, Maik Merten, Majid Valipour, Malcolm Rowe, Manish Goregaokar, Manish Tripathi, Manuel Martinez-Almeida, Manuel Rego Casasnovas, Marc Hoyois, Marc-André Choquette, Marc-André Lafortune, Marco Zehe, Marcus Bointon, Marcus Otterström, Marijn Kruisselbrink, Mark Amery, Mark Birbeck, Mark Davis, Mark Green, Mark Miller, Mark Nottingham, Mark Pilgrim, Mark Rogers, Mark Rowe, Mark Schenk, Mark Vickers, Mark Wilton-Jones, Markus Cadonau, Markus Stange, Martijn van der Ven, Martijn Wargers, Martin Atkins, Martin Chaov, Martin Dürst, Martin Honnen, Martin Janecke, Martin Kutschker, Martin Nilsson, Martin Thomson, Masataka Yakura, Masatoshi Kimura, Mason Freed, Mason Mize, Mathias Bynens, Mathieu Henri, Matias Larsson, Matt Brubeck, Matt Di Pasquale, Matt Falkenhagen, Matt Giuca, Matt Harding, Matt Schmidt, Matt Wright, Matthew Gaudet, Matthew Gregan, Matthew Mastracci, Matthew Noorenberghe, Matthew Raymond, Matthew Thomas, Matthew Tylee Atkinson, Mattias Waldau, Max Romantschuk, Maxim Tsoy, Mayeul Cantan, Menachem Salomon, Menno van Slooten, Micah Dubinko, Micah Nerren, Michael 'Ratt' Iannarelli, Michael A. Nachbaur, Michael A. Puls II, Michael Carter, Michael Daskalov, Michael Day, Michael Dyck, Michael Enright, Michael Ficarra, Michael Gratton, Michael Kohler, Michael McKelvey, Michael Nordman, Michael Powers, Michael Rakowski, Michael(tm) Smith, Michael Walmsley, Michal Zalewski, Michel Buffa, Michel Fortin, Michelangelo De Simone, Michiel van der Blonk, Miguel Casas-Sanchez, Mihai Şucan, Mihai Parparita, Mike Brown, Mike Dierken, Mike Dixon, Mike Hearn, Mike Pennisi, Mike Schinkel, Mike Shaver, Mikko Rantalainen, Mingye Wang, Mirko Brodesser, Mohamed Zergaoui, Mohammad Al Houssami, Mohammad Reza Zakerinasab, Momdo Nakamura, Morten Stenshorne, Mounir Lamouri, Ms2ger, mtrootyy, 邱慕安 (Mu-An Chiou), Mukilan Thiyagarajan, Mustaq Ahmed, Myles Borins, Nadia Heninger, Nate Chapin, NARUSE Yui, Navid Zolghadr, Neil Deakin, Neil Rashbrook, Neil Soiffer, Nereida Rondon, networkException, Nicholas Shanks, Nicholas Stimpson, Nicholas Zakas, Nickolay Ponomarev, Nicolas Gallagher, Nicolas Pena Moreno, Nicolò Ribaudo, Nidhi Jaju, Nikki Bee, Niklas Gögge, Nina Satragno, Noah Mendelsohn, Noah Slater, Noam Rosenthal, Noel Gordon, Nolan Waite, NoozNooz42, Norbert Lindenberg, Oisín Nolan, Ojan Vafai, Olaf Hoffmann, Olav Junker Kjær, Oldřich Vetešník, Oli Studholme, Oliver Hunt, Oliver Rigby, Olivia (Xiaoni) Lai, Olivier Gendrin, Olli Pettay, Ondřej Žára, Ori Avtalion, Oriol Brufau, oSand, Pablo Flouret, Patrick Dark, Patrick Garies, Patrick H. Lauke, Patrik Persson, Paul Adenot, Paul Lewis, Paul Norman, Per-Erik Brodin, 一丝 (percyley), Perry Smith, Peter Beverloo, Peter Karlsson, Peter Kasting, Peter Moulder, Peter Occil, Peter Stark, Peter Van der Beken, Peter van der Zee, Peter-Paul Koch, Phil Pickering, Philip Ahlberg, Philip Brembeck, Philip Taylor, Philip TAYLOR, Philippe De Ryck, Pierre-Arnaud Allumé, Pierre-Marie Dartus, Pierre-Yves Gérardy, Piers Wombwell, Pooja Sanklecha, Prashant Hiremath, Prashanth Chandra, Prateek Rungta, Pravir Gupta, Prayag Verma, 李普君 (Pujun Li), Rachid Finge, Rafael Weinstein, Rafał Miłecki, Rahul Purohit, Raj Doshi, Rajas Moonka, Rakina Zata Amni, Ralf Stoltze, Ralph Giles, Raphael Champeimont, Rebecca Star, Remci Mizkur, Remco, Remy Sharp, Rene Saarsoo, Rene Stach, Ric Hardacre, Rich Clark, Rich Doughty, Richa Rupela, Richard Gibson, Richard Ishida, Ricky Mondello, Rigo Wenning, Rikkert Koppes, Rimantas Liubertas, Riona Macnamara, Rob Buis, Rob Ennals, Rob Jellinghaus, Rob S, Rob Smith, Robert Blaut, Robert Collins, Robert Hogan, Robert Kieffer, Robert Linder, Robert Millan, Robert O'Callahan, Robert Sayre, Robin Berjon, Robin Schaufler, Rodger Combs, Roland Steiner, Roma Matusevich, Romain Deltour, Roman Ivanov, Roy Fielding, Rune Lillesveen, Russell Bicknell, Ruud Steltenpool, Ryan King, Ryan Landay, Ryan Sleevi, Ryo Kajiwara, Ryo Kato, Ryosuke Niwa, S. Mike Dierken, Salvatore Loreto, Sam Atkins, Sam Dutton, Sam Kuper, Sam Ruby, Sam Sneddon, Sam Weinig, Samikshya Chand, Samuel Bronson, Samy Kamkar, Sander van Lambalgen, Sanjoy Pal, Sanket Joshi, Sarah Gebauer, Sarven Capadisli, Satrujit Behera, Sayan Sivakumaran, Schalk Neethling, Scott Beardsley, Scott González, Scott Hess, Scott Miles, Scott O'Hara, Sean B. Palmer, Sean Feng, Sean Fraser, Sean Hayes, Sean Hogan, Sean Knapp, Sebastian Markbåge, Sebastian Schnitzenbaumer, Sendil Kumar N, Seth Call, Seth Dillingham, Shannon Moeller, Shanti Rao, Shaun Inman, Shiino Yuki, 贺师俊 (HE Shi-Jun), Shiki Okasaka, Shivani Sharma, shreyateeza, Shubheksha Jalan, Sidak Singh Aulakh, Sierk Bornemann, Sigbjørn Finne, Sigbjørn Vik, Silver Ghost, Silvia Pfeiffer, Šime Vidas, Simon Fraser, Simon Montagu, Simon Sapin, Yu Han, Simon Spiegel, Simon Wülker, skeww, Smylers, Srirama Chandra Sekhar Mogali, Stanton McCandlish, stasoid, Stefan Håkansson, Stefan Haustein, Stefan Santesson, Stefan Schumacher, Ştefan Vargyas, Stefan Weiss, Steffen Meschkat, Stephen Ma, Stephen Stewart, Stephen White, Steve Comstock, Steve Faulkner, Steve Fink, Steve Orvell, Steve Runyon, Steven Bennett, Steven Bingler, Steven Garrity, Steven Tate, Stewart Brodie, Stuart Ballard, Stuart Langridge, Stuart Parmenter, Subramanian Peruvemba, Sudhanshu Jaiswal, sudokus999, Sunava Dutta, Surma, Susan Borgrink, Susan Lesch, Sylvain Pasche, T.J. Crowder, Tab Atkins-Bittner, Taiju Tsuiki, Takashi Toyoshima, Takayoshi Kochi, Takeshi Yoshino, Tantek Çelik, 田村健人 (Kent TAMURA), Tawanda Moyo, Taylor Hunt, Ted Mielczarek, Terence Eden, Terrence Wood, Tetsuharu OHZEKI, Theresa O'Connor, Thijs van der Vossen, Thomas Broyer, Thomas Koetter, Thomas O'Connor, Tim Altman, Tim Dresser, Tim Johansson, Tim Nguyen, Tim Perry, Tim van der Lippe, TJ VanToll, Tobias Schneider, Tobie Langel, Toby Inkster, Todd Moody, Tom Baker, Tom Pike, Tom Schuster, Tom ten Thij, Tomasz Jakut, Tomek Wytrębowicz, Tommy Thorsen, Tony Ross, Tooru Fujisawa, Toru Kobayashi, Traian Captan, Travis Leithead, Trevor Rowbotham, Trevor Saunders, Trey Eckels, triple-underscore, Tristan Fraipont, Tristan Parisot, 保呂 毅 (Tsuyoshi Horo), Tyler Close, Valentin Gosu, Vardhan Gupta, Vas Sudanagunta, Veli Şenol, Victor Carbune, Victor Costan, Vipul Snehadeep Chawathe, Vitya Muhachev, Vlad Levin, Vladimir Katardjiev, Vladimir Vukićević, Vyacheslav Aristov, voracity, Walter Steiner, Wakaba, Wayne Carr, Wayne Pollock, Wellington Fernando de Macedo, Wenson Hsieh, Weston Ruter, Wilhelm Joys Andersen, Will Levine, Will Ray, William Chen, William Swanson, Willy Martin Aguirre Rodriguez, Wladimir Palant, Wojciech Mach, Wolfram Kriesing, Xan Gregg, xenotheme, XhmikosR, Xida Chen, Xidorn Quan, Xue Fuqiao, Yang Chen, Yao Xiao, Yash Handa, Yay295, Ye-Kui Wang, Yehuda Katz, Yi Xu, Yi-An Huang, Yngve Nysaeter Pettersen, Yoav Weiss, Yonathan Randolph, Yu Huojiang, Yuki Okushi, Yury Delendik, 平野裕 (Yutaka Hirano), Yuzo Fujishima, 西條柚 (Yuzu Saijo), Zhenbin Xu, 张智强 (Zhiqiang Zhang), Zoltan Herczeg, Zyachel, and Øistein E. Andersen, for their useful comments, both large and small, that have led to changes to this specification over the years.
Thanks also to everyone who has ever posted about HTML to their blogs, public mailing lists, or forums, including all the contributors to the various W3C HTML WG lists and the various WHATWG lists.
Special thanks to Richard Williamson for creating the first implementation of
canvas in Safari, from which the canvas feature was designed.
Special thanks also to the Microsoft employees who first implemented the event-based
drag-and-drop mechanism, contenteditable, and other
features first widely deployed by the Windows Internet Explorer browser.
Special thanks and $10,000 to David Hyatt who came up with a broken implementation of the adoption agency algorithm that the editor had to reverse engineer and fix before using it in the parsing section.
Thanks to the participants of the microdata usability study for allowing us to use their mistakes as a guide for designing the microdata feature.
Thanks to the many sources that provided inspiration for the examples used in the specification.
Thanks also to the Microsoft blogging community for some ideas, to the attendees of the W3C Workshop on Web Applications and Compound Documents for inspiration, to the #mrt crew, the #mrt.no crew, and the #whatwg crew, and to Pillar and Hedral for their ideas and support.
Thanks to Igor Zhbanov for generating PDF versions of the specification.
Special thanks to the RICG for developing
the picture element and related features; in particular thanks to Adrian Bateman,
Bruce Lawson, David Newton, Ilya Grigorik, John Schoenick, Leon de Rijke, Mat Marquis, Marcos
Cáceres, Tab Atkins, Theresa O'Connor, and Yoav Weiss for their contributions.
Special thanks to the WPWG for incubating the custom elements feature. In particular, thanks to David Hyatt and Ian Hickson for their influence through the XBL specifications, Dimitri Glazkov for the first draft of the custom elements specification, and to Alex Komoroske, Alex Russell, Andres Rios, Boris Zbarsky, Brian Kardell, Daniel Buchner, Dominic Cooney, Erik Arvidsson, Elliott Sprehn, Hajime Morrita, Hayato Ito, Jan Miksovsky, Jonas Sicking, Olli Pettay, Rafael Weinstein, Roland Steiner, Ryosuke Niwa, Scott Miles, Steve Faulkner, Steve Orvell, Tab Atkins, Theresa O'Connor, Tim Perry, and William Chen for their contributions.
Special thanks to the CSSWG for developing the worklets. In particular, thanks to Ian Kilpatrick for his work as editor of the original worklets specification.
For about ten years starting in 2003, this standard was almost entirely written by Ian Hickson (Google, ian@hixie.ch).
Starting in 2015, the editor group expanded. It is currently maintained by Anne van Kesteren (Apple, annevk@annevk.nl), Domenic Denicola (Google, d@domenic.me) Dominic Farolino (Google, domfarolino@gmail.com), Philip Jägenstedt (Google, philip@foolip.org), and Simon Pieters (Mozilla, zcorpan@gmail.com).
The image in the introduction is based on a photo by Wonderlane. (CC BY 2.0)
The image of the wolf in the embedded content introduction is based on a photo by Barry O'Neill. (Public domain)
The image of the kettlebell swing in the embedded content introduction is based on a photo by kokkarina. (CC0 1.0)
The Blue Robot Player sprite used in the canvas demo is based on a work by JohnColburn. (CC BY-SA 3.0)
The photograph of robot 148 climbing the tower at the FIRST Robotics Competition 2013 Silicon Valley Regional is based on a work by Lenore Edman. (CC BY 2.0)
The diagram showing how async and defer impact script loading is based on a
similar diagram from a
blog post by Peter Beverloo.
(CC0 1.0)
The image decoding demo used to demonstrate module-based workers draws on some example code from a tutorial by Ilmari Heikkinen. (CC BY 3.0)
The <flag-icon> example was inspired by a custom element by Steven
Skelton. (MIT)
Part of the revision history of the
picture element and related features can be found in the ResponsiveImagesCG/picture-element
repository, which is available under the W3C Software and
Document License.
Part of the revision history of the theme-color metadata name can be found in the whatwg/meta-theme-color
repository, which is available under CC0.
Part of the revision history of the custom elements feature can be found in the w3c/webcomponents repository, which
is available under the W3C Software and
Document License.
Part of the revision history of the innerText getter and setter can be found in the rocallahan/innerText-spec
repository, which is available under CC0.
Part of the revision history of the worklets feature can be found in the w3c/css-houdini-drafts
repository, which is available under the W3C Software and
Document License.
Part of the revision history of the import maps feature can be found in the WICG/import-maps
repository, which is available under the W3C Software and
Document License.
Part of the revision history of the navigation API feature can be found in the WICG/navigation-api
repository, which is available under the W3C Software and
Document License.
Part of the revision history of the Close requests and close watchers section can be
found in the WICG/close-watcher
repository, which is available under the W3C Software and
Document License.
Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License. To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.
This is the Living Standard. Those interested in the patent-review version should view the Living Standard Review Draft.